ISO 28005-1:2024

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 .
...