ISO 28005-1:2024
(Main)Ships and marine technology - Electronic port clearance (EPC) - Part 1: Message structures and application programming interfaces
Ships and marine technology - Electronic port clearance (EPC) - Part 1: Message structures and application programming interfaces
This document defines the principles, methods and requirements for message exchanges between ships, ship representatives, and other shore parties via a peer-to-peer communication system. This document defines the message structure, including how the data content is assembled from other parts of the ISO 28005 series, and how digital signatures for authentication, integrity, and confidentiality of the message can be used. It also specifies a transport protocol, the basic message exchange patterns, and the protocol related roles of each party in the message exchange. Furthermore, it specifies how more specific message implementation guides (MIGs) are provided for each type of communication application.
Navires et technologie maritime — Opérations portuaires assistées par systèmes électroniques — Partie 1: Structures des messages et interfaces de programmation des applications
General Information
- Status
- Published
- Publication Date
- 08-Dec-2024
- Technical Committee
- ISO/TC 8/SC 11 - Intermodal and Short Sea Shipping
- Drafting Committee
- ISO/TC 8/SC 11 - Intermodal and Short Sea Shipping
- Current Stage
- 6060 - International Standard published
- Start Date
- 09-Dec-2024
- Due Date
- 12-Oct-2024
- Completion Date
- 09-Dec-2024
Relations
- Effective Date
- 06-Jun-2022
Overview - ISO 28005-1:2024 (Electronic port clearance, Part 1)
ISO 28005-1:2024 defines the message structures and application programming interfaces (APIs) for Electronic Port Clearance (EPC) in the ships and marine technology domain. The standard establishes principles, methods and requirements for secure, peer-to-peer message exchanges between ships, ship representatives and shore parties. It covers how message content is assembled from the ISO 28005 series, the use of digital signatures for authentication, integrity and confidentiality, a specified transport protocol, basic message exchange patterns and role definitions for each participant. The document also defines how Message Implementation Guides (MIGs) are produced for specific communication applications.
Key technical topics and requirements
- Message structures and XSD definitions: clear rules for XML Schema (XSD) files, including file structure, naming and versioning, character set and namespace handling.
- XML design principles: conventions such as avoiding XML attributes, default minOccurs/maxOccurs values, element ordering and signalling empty tags.
- Standardized data types: adapted epc:* types (e.g., epc:date, epc:dateTime, epc:string, epc:anyURI) and general ISO 28005 data types for common maritime data elements.
- Security requirements: use of digital signatures and authentication tokens to ensure message integrity, confidentiality and non-repudiation.
- Transport protocol and exchange patterns: a specified transport method and defined protocol roles and basic message exchange patterns for peer-to-peer EPC messaging.
- Message Implementation Guides (MIGs): mechanism to create application-specific guides for particular clearance workflows and message types.
- Cross-reference to ISO 28005 series: mechanisms to assemble data content from other parts of the series (e.g., ISO 28005-2).
Practical applications and users
ISO 28005-1 is intended for organizations that implement or operate electronic port clearance and ship-to-shore messaging:
- Ship operators and ship agents - automate pre-arrival notifications, clearance requests and reduce paperwork.
- Port authorities and maritime administrations - receive standardized, authenticated messages for regulatory checks and arrival clearance.
- Port community systems and terminal operators - integrate EPC APIs into local workflows and systems.
- Software vendors and system integrators - implement the XSDs, APIs, security mechanisms and MIGs to enable interoperable solutions.
- Regulatory bodies - specify compliance requirements and support national e‑clearance frameworks.
Related standards
- ISO 28005 series (other parts provide complementary data models and implementation guidance)
- ISO 28005-2:2021 referenced for data type definitions and integration
Keywords: ISO 28005-1, Electronic port clearance, EPC, message structures, APIs, XSD, digital signatures, transport protocol, maritime communications, Message Implementation Guides (MIGs).
Frequently Asked Questions
ISO 28005-1:2024 is a standard published by the International Organization for Standardization (ISO). Its full title is "Ships and marine technology - Electronic port clearance (EPC) - Part 1: Message structures and application programming interfaces". This standard covers: This document defines the principles, methods and requirements for message exchanges between ships, ship representatives, and other shore parties via a peer-to-peer communication system. This document defines the message structure, including how the data content is assembled from other parts of the ISO 28005 series, and how digital signatures for authentication, integrity, and confidentiality of the message can be used. It also specifies a transport protocol, the basic message exchange patterns, and the protocol related roles of each party in the message exchange. Furthermore, it specifies how more specific message implementation guides (MIGs) are provided for each type of communication application.
This document defines the principles, methods and requirements for message exchanges between ships, ship representatives, and other shore parties via a peer-to-peer communication system. This document defines the message structure, including how the data content is assembled from other parts of the ISO 28005 series, and how digital signatures for authentication, integrity, and confidentiality of the message can be used. It also specifies a transport protocol, the basic message exchange patterns, and the protocol related roles of each party in the message exchange. Furthermore, it specifies how more specific message implementation guides (MIGs) are provided for each type of communication application.
ISO 28005-1:2024 is classified under the following ICS (International Classification for Standards) categories: 35.240.60 - IT applications in transport; 47.020.99 - Other standards related to shipbuilding and marine structures. The ICS classification helps identify the subject area and facilitates finding related standards.
ISO 28005-1:2024 has the following relationships with other standards: It is inter standard links to ISO 28005-1:2013. Understanding these relationships helps ensure you are using the most current and applicable version of the standard.
You can purchase ISO 28005-1:2024 directly from iTeh Standards. The document is available in PDF format and is delivered instantly after payment. Add the standard to your cart and complete the secure checkout process. iTeh Standards is an authorized distributor of ISO standards.
Standards Content (Sample)
International
Standard
ISO 28005-1
Second edition
Ships and marine technology —
2024-12
Electronic port clearance (EPC) —
Part 1:
Message structures and application
programming interfaces
Navires et technologie maritime — Opérations portuaires
assistées par systèmes électroniques —
Partie 1: Structures des messages et interfaces de programmation
des applications
Reference number
© ISO 2024
All rights reserved. Unless otherwise specified, or required in the context of its implementation, no part of this publication may
be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on
the internet or an intranet, without prior written permission. Permission can be requested from either ISO at the address below
or ISO’s member body in the country of the requester.
ISO copyright office
CP 401 • Ch. de Blandonnet 8
CH-1214 Vernier, Geneva
Phone: +41 22 749 01 11
Email: copyright@iso.org
Website: www.iso.org
Published in Switzerland
ii
Contents Page
Foreword .ix
Introduction .xi
1 Scope . 1
2 Normative references . 1
3 Terms, definitions, and abbreviated terms . 1
3.1 Terms and definitions .1
3.2 Abbreviated terms .5
4 Structure of XSD data type and object definitions . 6
4.1 General .6
4.2 Principles for XML descriptions in the ISO 28005 series .7
4.2.1 No use of XML attributes .7
4.2.2 Defaults for minOccurs and maxOccurs .7
4.2.3 Signalling empty XML tags .7
4.2.4 Order of child elements in XSD files .7
4.2.5 Character set .7
4.2.6 Principles for defining types with code lists.7
4.2.7 XSD name space for general XSD data types .8
4.2.8 ISO 28005 name space .8
4.2.9 Use of Xpath expressions .8
4.3 Structure of clauses defining data types.8
4.3.1 Clause and data type name .8
4.3.2 Definition .8
4.3.3 Type defined as XSD code .9
4.3.4 Representation .9
4.4 Creating valid XSD schema files .9
4.4.1 File structure .9
4.4.2 Numbering of XSD files and message version code .10
4.4.3 Location of XSD files .11
4.5 Reference to data types defined in ISO 28005-2:2021 .11
5 Adapted XSD data types for ISO 28005 .12
5.1 General . 12
5.2 epc:anyURI – Generalized URI . 12
5.2.1 Definition . 12
5.2.2 Type . 12
5.2.3 Representation . 12
5.3 epc: boolean – Boolean flag . 12
5.3.1 Definition . 12
5.3.2 Type . 12
5.3.3 Representation . 12
5.4 epc:date – General date . 12
5.4.1 Definition . 12
5.4.2 Type . 12
5.4.3 Representation . 13
5.5 epc:dateTime – Time and date, with time zone . 13
5.5.1 Definition . 13
5.5.2 Type . 13
5.5.3 Representation . 13
5.6 epc:decimal – decimal number . 13
5.6.1 Definition . 13
5.6.2 Type . 13
5.6.3 Representation . 13
5.7 epc:duration – Time duration.14
5.7.1 Definition .14
iii
5.7.2 Type .14
5.7.3 Representation .14
5.8 epc:int – Integer number.14
5.8.1 Definition .14
5.8.2 Type .14
5.8.3 Representation .14
5.9 epc:string – General string .14
5.9.1 Definition .14
5.9.2 Type .14
5.9.3 Representation . 15
5.10 epc:token – Computer-understandable string . 15
5.10.1 Definition . 15
5.10.2 Type . 15
5.10.3 Representation . 15
5.11 epc:xpath – Identification of an XML data item . 15
5.11.1 Definition . 15
5.11.2 Type . 15
5.11.3 Representation . 15
6 General ISO 28005 data types .15
6.1 General . 15
6.2 epc: AuthenticatorType – Authenticator of information . 15
6.2.1 Definition . 15
6.2.2 Type .16
6.2.3 Representation .16
6.3 epc:AuthorizationTokenType – Authorization token .16
6.3.1 Definition .16
6.3.2 Type .16
6.3.3 Representation .16
6.4 epc:ContactInfoType – Contact information .16
6.4.1 Definition .16
6.4.2 Type .17
6.4.3 Representation .17
6.5 epc:CommunicationNumberType – Communication number information .17
6.5.1 Definition .17
6.5.2 Type .17
6.5.3 Representation .18
6.6 epc:CountryCodeContentType – Country identification .18
6.6.1 Definition .18
6.6.2 Type .18
6.6.3 Representation .18
6.7 epc:CountrySubdivisionCodeContentType – Country subdivision identification .18
6.7.1 Definition .18
6.7.2 Type .18
6.7.3 Representation .19
6.8 epc:CrewDutyType – Duty onboard or on shore .19
6.8.1 Definition .19
6.8.2 Type .19
6.8.3 Representation .19
6.9 epc:LocationType – Identification of a location .19
6.9.1 Definition .19
6.9.2 Type .19
6.9.3 Representation .21
6.10 epc:NameType – Name of person.21
6.10.1 Definition .21
6.10.2 Type .21
6.10.3 Representation .21
6.11 epc:OrganizationType – Description of an organization. 22
6.11.1 Definition . 22
iv
6.11.2 Type . 22
6.11.3 Representation . 22
6.12 epc:PostalAddressType – A postal mail address . 22
6.12.1 Definition . 22
6.12.2 Type . 22
6.12.3 Representation . 23
6.13 epc:ShipIDType – Ship identity . 23
6.13.1 Definition . 23
6.13.2 Type . 23
6.13.3 Representation . 23
6.14 epc:ReportingSystemType – Name of a reporting system .24
6.14.1 Definition .24
6.14.2 Type .24
6.14.3 Representation .24
6.15 epc:AttachmentType – Reference to an attached document .24
6.15.1 Definition .24
6.15.2 Type .24
6.15.3 Representation .24
6.16 epc:ReferenceCodeType – General reference code . 25
6.16.1 Definition . 25
6.16.2 Type . 25
6.16.3 Representation . 25
6.17 epc:SystemIdType – Identity code for a software system . 25
6.17.1 Definition . 25
6.17.2 Type . 25
6.17.3 Representation . 25
6.18 epc:SignatureCertificateIdType – Name of digital signature holder . 26
6.18.1 Definition . 26
6.18.2 Type . 26
6.18.3 Representation . 26
6.19 epc:VersionType – Version code . 26
6.19.1 Definition . 26
6.19.2 Type . 26
6.19.3 Representation .27
7 I SO 28005 design principles .27
7.1 Harmonization with the IMO reference data model .27
7.2 Fully automated machine to machine .27
7.3 Using carrier independent and internet-based protocols . 28
7.4 General format of message sequence diagrams . 28
7.5 Sender and receiver versus client and server — asynchronous message transfers . 29
7.6 Generalization of service . 30
7.7 Different levels of sessions . . 30
7.7.1 HTTP session . 30
7.7.2 Session .31
7.7.3 Session context .32
7.8 One service per request and session . 33
7.9 Linking receivers to service providers . 33
7.10 Service request states . 33
7.10.1 Message processing . 33
7.10.2 State diagram for service requests . 34
7.10.3 Message functions . 36
7.10.4 Specification of request timeout . 36
7.10.5 Message and service request return values .37
7.11 Send data once only .37
7.12 Message context .37
7.13 General message structure . . 39
7.14 Digital signatures . 40
7.15 Secure data transfer . 40
v
7.16 Additional authorization for accessing API. 40
7.17 Message implementation guide .41
7.18 Other formats than XML for the message body .41
7.19 No explicit service discovery .41
8 Message exchange patterns . 41
8.1 General rules .41
8.1.1 Application of this specification .41
8.1.2 Use of reference codes .42
8.1.3 Use of final flag in message header .42
8.1.4 Use of service timeout or session context end .43
8.1.5 Status and error codes .43
8.1.6 Multiple senders . . 44
8.1.7 Interleaving update requests with status messages . .45
8.2 Sequence diagrams .45
8.2.1 Pattern 1: Service request and updates .45
8.2.2 Pattern 2: Status poll .47
8.2.3 Pattern 3: Simple report .47
8.2.4 Pattern 4: Request information . 48
8.2.5 Pattern 5: Subscribe to service or information . 48
9 Using HTTP multi-part message .49
9.1 General . 49
9.2 Example of an ISO 28005-1 multi-part message. 50
9.3 Content-Type: multipart/form-data . 50
9.4 Content-Encoding: gzip .51
9.5 Prose text.51
9.6 Content-Type: application, image or other .51
9.7 Content-Disposition: form-data; name = name; filename = file.name; .51
10 Definitions related to the message header part .52
10.1 General .52
10.2 epc:MessageFunctionCodeContentType – Message function code .52
10.2.1 Definition .52
10.2.2 Type .52
10.2.3 Representation .52
10.3 epc:ReplyInformationType – Type of sender response code .52
10.3.1 Definition .52
10.3.2 Type .52
10.3.3 Representation . 53
10.4 epc:MessageBodyFormatContentType – Format of body data . 53
10.4.1 Definition . 53
10.4.2 Type . 53
10.4.3 Representation . 53
10.5 epc:ServiceTypeCodeContentType – Code for identification of service type . 53
10.5.1 Definition . 53
10.5.2 Type . 54
10.5.3 Representation . 54
10.6 epc:ServiceCodeContentType – Code for identification of a service in a group . 54
10.6.1 Definition . 54
10.6.2 Type . 54
10.6.3 Representation . 54
10.7 epc:StatusType – General message and service request status and error codes . 54
10.7.1 Definition . 54
10.7.2 Type . 54
10.7.3 Representation . 55
10.8 epc:SpecialAttachmentType – Description of special attachment . 55
10.8.1 Definition .
...
Die Norm ISO 28005-1:2024 bietet eine umfassende Grundlage für den elektronischen Hafenabfertigungsprozess (Electronic Port Clearance, EPC) im maritimen Sektor. Die Norm ist besonders relevant für Schiffe, Schiffsvertreter und andere Beteiligte an der Küste, da sie die Prinzipien, Methoden und Anforderungen für den Nachrichtenaustausch über ein Peer-to-Peer-Kommunikationssystem definiert. Ein wesentliches Merkmal dieser Norm ist die klare Festlegung der Nachrichtenstruktur. Die Norm beschreibt detailliert, wie die Dateninhalte aus anderen Teilen der ISO 28005-Serie zusammengesetzt werden, was die Interoperabilität zwischen verschiedenen Systemen fördert. Insbesondere wird auch die Implementierung digitaler Signaturen behandelt, die für die Authentifikation, Integrität und Vertraulichkeit der Nachrichten von entscheidender Bedeutung sind. Die Norm spezifiziert auch ein Transportprotokoll sowie grundlegende Muster für den Nachrichtenaustausch, was eine standardisierte Kommunikation zwischen den beteiligten Parteien ermöglicht. Diese Struktur reduziert den administrativen Aufwand und beschleunigt den Informationsaustausch erheblich. Des Weiteren behandelt die Norm die rollenbezogenen Aufgaben jeder Partei während des Nachrichtenaustauschs, was zur Klarheit der Interaktionen beiträgt. Ein weiterer starker Punkt der ISO 28005-1:2024 ist die Bereitstellung spezifischer Implementierungsleitfäden für jede Art von Kommunikationsanwendung. Diese Implementierungsleitfäden (MIGs) bieten praktische Anleitungen für die korrekte Anwendung der Norm und unterstützen Organisationen dabei, die Anforderungen effizient umzusetzen. Insgesamt hebt sich die ISO 28005-1:2024 durch ihre umfassende Herangehensweise und die klaren Vorgaben zur Standardisierung des elektronischen Hafenabfertigungsprozesses hervor. Ihre Relevanz ist nicht nur auf maritime Unternehmen beschränkt, sondern erstreckt sich auch auf alle Akteure, die im Bereich der Hafenabfertigung tätig sind, und leistet somit einen bedeutenden Beitrag zur Effizienz und Sicherheit im maritimen Sektor.
ISO 28005-1:2024 sets a significant foundation for the implementation of Electronic Port Clearance (EPC) within the maritime industry. The standard excels in defining the principles, methods, and requirements necessary for effective message exchanges between ships, their representatives, and shore parties. By adopting a peer-to-peer communication system, the standard enhances the efficiency of maritime operations. One of the strengths of ISO 28005-1:2024 is its detailed specification of message structures. It effectively outlines how data content can be assembled from various components within the ISO 28005 series, providing a clear framework that facilitates interoperability among different maritime systems. The inclusion of digital signatures for authentication, integrity, and confidentiality boosts security, ensuring that messages exchanged are reliable and protected against unauthorized access. Moreover, the standard specifies a transport protocol and elucidates the basic message exchange patterns, which are essential for enabling seamless communication between stakeholders. Clearly defined roles associated with the protocol help streamline interactions, reducing confusion and improving operational efficiency. Another commendable aspect of ISO 28005-1:2024 is the provision of Message Implementation Guides (MIGs) tailored for different types of communication applications. This ensures that specific needs and scenarios can be addressed, allowing for flexibility and adaptability in diverse maritime contexts. Overall, ISO 28005-1:2024 is a highly relevant standard that addresses key aspects of electronic communication in the shipping industry. Its comprehensive approach to message structure, security, and implementation guidelines significantly contributes to enhancing collaborative efforts in maritime operations, promoting a more efficient and secure environment for port clearance processes.
La norme ISO 28005-1:2024 représente une avancée significative dans le domaine de la technologie maritime et de l'électronique portuaire, en se concentrant sur les structures de messages et les interfaces de programmation applicatives (API) pour les échanges de messages entre navires et parties terrestres. Son champ d'application est clairement défini, permettant une compréhension approfondie des principes et des méthodes de communication peer-to-peer dans le contexte maritime. Un des points forts de cette norme est sa capacité à standardiser la structure des messages, garantissant ainsi que les données échangées sont organisées et interprétées de manière cohérente. Cela favorise non seulement l'efficacité des opérations portuaires, mais améliore également la sécurité des informations, grâce à l'intégration de signatures numériques pour l'authentification, l'intégrité et la confidentialité des messages échangés. De plus, la norme ISO 28005-1:2024 spécifie un protocole de transport, établissant des modèles d'échange de messages de base qui sont essentiels pour le fonctionnement harmonieux des différentes parties impliquées dans le processus d'échange. Cette précision dans la définition des rôles de chaque partie participant à l'échange de messages renforce la clarté et minimise les risques de malentendus qui pourraient affecter les opérations. Il est également notable que la norme prévoit des guides d'implémentation des messages (MIG) spécifiques pour chaque type d'application de communication. Cela permet une flexibilité et une personnalisation qui peuvent répondre aux besoins variés des différentes parties prenantes, rendant ainsi cette norme non seulement pertinente mais également hautement adaptable dans un secteur en constante évolution. En somme, la norme ISO 28005-1:2024 se distingue par sa pertinence dans l'amélioration de l'efficacité et de la sécurité des échanges électroniques dans le secteur maritime, tout en fournissant des fondations solides pour l'avenir des technologies de communication portuaire.
ISO 28005-1:2024は、船舶と海洋技術の分野における電子港清算（EPC）のための基準の第1部であり、メッセージ構造およびアプリケーションプログラミングインターフェイスに関する重要な文書です。この標準は、船舶、船舶代表者、および他の陸上関係者との間でのピアツーピア通信システムを通じたメッセージ交換の原則、方法、および要件を定義しています。 この標準の強みは、明確に定義されたメッセージ構造にあります。ISO 28005シリーズの他の部分からデータ内容がどのように組み立てられるかを示し、メッセージの認証、整合性、および機密性のためにデジタル署名を利用する方法も明記しています。これにより、船舶における情報伝達の信頼性が向上し、効率的なコミュニケーションが実現されます。 さらに、ISO 28005-1:2024は、メッセージ交換のための基本的なパターンや、各関係者の役割も明示しています。このように、関係者間の役割分担を明確にすることで、業務プロセスの整合性が確保され、円滑な情報フローが実現されます。また、各通信アプリケーションタイプに対して、より具体的なメッセージ実装ガイド（MIG）が提供されることも重要な要素です。 ISO 28005-1は、業界における国際的な通信の標準化を促進し、船舶と陸上の間のスムーズな取引を可能にするために非常に関連性の高い基準です。これにより、国際貿易や海運業界における効率性と透明性が向上すると期待されます。
ISO 28005-1:2024는 전자 항구 통관(EPC)을 위한 표준으로, 해양 기술과 관련하여 선박, 선박 대리인 및 해안의 다른 당사자 간의 메시지 교환을 위한 원칙, 방법 및 요구 사항을 정의합니다. 이 문서는 피어 투 피어 통신 시스템을 통해 이루어지는 메시지 교환의 기본에 대한 명확한 가이드를 제공합니다. 이 표준의 범위는 메시지 구조, 데이터 내용의 조합 방법 및 메시지의 인증, 무결성 및 기밀성을 위한 디지털 서명 사용 방법을 포함하여, 통신의 기본적인 메시지 교환 패턴과 각 당사자의 역할을 구체적으로 명시합니다. 이는 특히 해양 분야에서의 통신 효율성을 높이는데 크게 기여할 것입니다. ISO 28005-1:2024의 주요 강점은 각종 커뮤니케이션 애플리케이션의 종류에 맞춰 더욱 세분화된 메시지 구현 가이드(MIGs)를 제공함으로써 사용자의 접근성을 높인다는 점입니다. 이는 사용자에게 보다 명확한 지침을 제공하며, 실제 상황에서의 구현 가능성을 극대화합니다. 또한, 디지털 서명 및 전송 프로토콜의 명확한 정의는 메시지의 안전성과 유효성을 보장합니다. 이 표준은 해양 산업과 관련된 전자 통신의 중요성이 증가하는 현재의 환경에서 매우 관련성이 높습니다. 특히 세계적인 물류와 해운 산업의 디지털화가 진행됨에 따라, 이 문서가 제시하는 표준은 향후 항구 통관 절차의 효율성을 획기적으로 개선할 것으로 기대됩니다. ISO 28005-1:2024는 해양 기술의 발전에 있어 중요한 이정표가 될 것입니다.
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.
Loading comments...