Physical Address
304 North Cardinal St.
Dorchester Center, MA 02124
ISO 28005-1:2024 Electronic Port Clearance — Message Structures and APIs
Standardized digital communication framework for maritime port clearance operations
ISO 28005-1:2024 defines the message structures and application programming interfaces (APIs) for Electronic Port Clearance (EPC) systems, enabling seamless digital communication between ships, port authorities, customs, immigration, health authorities, and other regulatory agencies. This standard replaces traditional paper-based port clearance procedures with efficient XML-based data exchange, significantly reducing vessel turnaround times and administrative overhead for all stakeholders in the maritime domain.
ISO 28005-1 adopts a RESTful API architecture with XML message payloads. This modern approach ensures interoperability across different maritime single window systems while supporting both synchronous request-response and asynchronous event-driven communication patterns for different port clearance scenarios.
Message Structure and XML Schema Design Principles
The standard defines comprehensive XML Schema Definitions (XSD) for all port clearance messages, organized into logical message families. Key message types include arrival notifications, cargo declarations, crew and passenger lists, ship stores declarations, maritime declarations of health, and departure requests. Each message type follows a standardized structure with mandatory and optional data elements organized in a hierarchical format, enabling automated validation at both the sending and receiving ends. The XSD design principles ensure extensibility while maintaining backward compatibility.
| Message Type | Purpose | Key Data Elements | Priority |
|---|---|---|---|
| ArrivalNotification | Notify port of impending vessel arrival | Vessel IMO number, call sign, ETA, last port of call, cargo summary, crew count, passenger count | High |
| CargoDeclaration | Declare all cargo carried on board | Bill of lading references, cargo classification codes, gross/net weight, container numbers, hazardous class | High |
| CrewList | Report crew composition and details | Surname, given name, nationality, rank, passport number, seaman book number, date of birth | High |
| ShipStoresDeclaration | Declare ship provisions, supplies, and bonded stores | Item categories (UN/CEFACT codes), quantities, bonded status, duty-paid status, dangerous goods | Medium |
| HealthDeclaration | Maritime declaration of health | Port health questions, illness on board, sanitation measures, vaccination status of crew | High |
| DepartureRequest | Request formal clearance to depart | Next port of call, ETD, final cargo summary, crew changes, stores taken, waste delivered | High |
Implementers must strictly adhere to the XSD namespace conventions defined in ISO 28005-1. Custom extensions must use separate namespaces with organization-specific prefixes to maintain forward compatibility with future versions of the standard and to prevent namespace collisions between different implementing systems.
API Design Patterns and Implementation Considerations
From an engineering perspective, ISO 28005-1 specifies that EPC APIs should implement at least TLS 1.3 for transport security, support OAuth 2.0 with client credentials grant for machine-to-machine authentication, and provide idempotency guarantees for critical submissions through unique message identifiers. The standard recommends JSON Web Signatures (JWS) for non-repudiation of submitted declarations, ensuring that senders cannot deny having submitted specific clearance information. API endpoints follow a consistent naming pattern: /api/v1/{message-type} for submissions and /api/v1/{message-type}/{id} for status queries and retrieval.
The standard emphasizes offline capability, recognizing that ships may have intermittent or high-latency connectivity, particularly when at sea. Messages can be prepared onboard using standardized forms and queued for transmission when connectivity becomes available. The API supports batch submissions for multiple messages and provides detailed validation responses with specific error codes so that errors can be identified and corrected before formal submission to regulatory authorities.
Ports implementing ISO 28005-1-compliant EPC systems report average clearance time reductions from 4-6 hours to under 30 minutes. The standardized API approach eliminates the need for costly bilateral integration agreements between each ship agent and port authority, enabling plug-and-play connectivity.
Security Architecture and Data Privacy Protections
ISO 28005-1 mandates end-to-end encryption for all port clearance data, with particular attention to commercially sensitive information such as cargo values, charter party details, and crew personal data. The standard provides data retention guidelines aligned with national maritime regulations, specifies minimum audit logging requirements for all API interactions, and requires support for data subject access requests under applicable privacy regulations such as GDPR.
Q: Is ISO 28005-1 compatible with existing maritime single window systems?
A: Yes, the standard is designed to align with IMO FAL Convention requirements and can be implemented either as an enhancement to existing single window platforms or as a standalone EPC solution with integration adapters.
A: Yes, the standard is designed to align with IMO FAL Convention requirements and can be implemented either as an enhancement to existing single window platforms or as a standalone EPC solution with integration adapters.
Q: Does the standard support both ship-to-shore and shore-to-shore communication?
A: Yes, ISO 28005-1 covers ship-to-port submission of declarations, port-to-agency data exchange with customs and immigration, and port-to-port communication for transit clearance and advance notification.
A: Yes, ISO 28005-1 covers ship-to-port submission of declarations, port-to-agency data exchange with customs and immigration, and port-to-port communication for transit clearance and advance notification.
Q: What connectivity requirements are assumed for shipboard systems?
A: The standard is designed for IP-based networks but includes comprehensive offline capabilities. Ships can author and cache messages while offline, transmitting them when satellite or terrestrial connectivity becomes available.
A: The standard is designed for IP-based networks but includes comprehensive offline capabilities. Ships can author and cache messages while offline, transmitting them when satellite or terrestrial connectivity becomes available.
Implementation Roadmap and System Integration Strategy
Implementing an ISO 28005-1 compliant EPC system requires a structured approach spanning multiple phases. The initial assessment phase involves mapping existing port clearance workflows, identifying stakeholders and their data requirements, and documenting current data formats and exchange mechanisms. The design phase includes defining message profiles for each clearance scenario, establishing API security policies, and planning integration with existing port legacy systems. The development phase covers API implementation, XSD schema deployment, and connectivity testing with pilot users. The rollout phase involves phased deployment starting with arrival notification messages, followed by cargo declarations, crew lists, and finally departure requests.
System integration strategy must address connectivity with existing Port Community Systems, customs declaration platforms, and national maritime single window environments. The standard recommends an adapter-based integration pattern where legacy system data formats are transformed to ISO 28005-1 compliant XML messages through middleware adapters. This approach minimizes disruption to existing systems while enabling progressive migration to the standardized format.
Q: What is the typical implementation timeline for a port EPC system?
A: Typical implementation timelines range from 6-12 months for a medium-sized port, including system design, development, integration testing, user training, and phased rollout. Smaller ports with simpler operations may complete implementation in 3-6 months.
A: Typical implementation timelines range from 6-12 months for a medium-sized port, including system design, development, integration testing, user training, and phased rollout. Smaller ports with simpler operations may complete implementation in 3-6 months.
Q: How is data synchronization handled when multiple systems update the same clearance data?
A: The standard defines data ownership and master data management principles. Each data element has a designated authoritative source, and update conflicts are resolved through timestamp-based versioning.
A: The standard defines data ownership and master data management principles. Each data element has a designated authoritative source, and update conflicts are resolved through timestamp-based versioning.
Technical Standards and Interoperability Testing
ISO 28005-1 emphasizes the importance of interoperability testing between different EPC implementations. The standard defines a conformance testing framework including test scenarios for each message type, validation rules for message content, and performance benchmarks for response times and system availability. Port authorities implementing EPC systems should establish a test environment where system vendors can verify their implementations against the standard before deployment. The standard also specifies minimum service level requirements including 99.5% system availability during port operating hours and maximum response times for synchronous API calls.
