Magyar verzió

1. Introduction

The DCC API (Directive on Administrative Cooperation API) project contains the public schema definitions for the M2M (Machine-to-Machine) interface of the tax data exchange under Directive 2011/16/EU (DAC).

The project aims to provide a unified, secure, and efficient electronic data exchange framework that consolidates and supports all data exchange processes prescribed by the EU DAC directive. The system establishes a uniform foundation for interoperability, transparency, and data security, facilitating a higher level of tax cooperation within the European Union.

1.1. DAC9 - GloBE Information Return (Pillar Two)

DAC9 is one of the most important tax data exchange services under Directive 2011/16/EU (DAC), providing XML schemas for reporting the global minimum tax. The DCC-API DAC9 modules contain the implementation of the GloBE Information Return (Pillar Two) XML schemas, developed by Hungary in cooperation with the OECD, based on the following documents:

  1. OECD (2025), GloBE Information Return (Pillar Two) XML Schema: User Guide for Tax Administrations, OECD Publishing, Paris, https://doi.org/10.1787/c594935a-en.

  2. OECD (2025), Tax Challenges Arising from the Digitalisation of the Economy - Consolidated Commentary to the Global Anti-Base Erosion Model Rules (2025): Inclusive Framework on BEPS, OECD/G20 Base Erosion and Profit Shifting Project, OECD Publishing, Paris, https://doi.org/10.1787/a551b351-en.

  3. OECD (2025), Tax Challenges Arising from the Digitalisation of the Economy - GloBE Information Return (January 2025): Inclusive Framework on BEPS, OECD/G20 Base Erosion and Profit Shifting Project, OECD Publishing, Paris, https://doi.org/10.1787/a05ec99a-en.

2. Documentation overview

The following documents make up the DCC API development documentation:

Document Description

Architecture

Project structure, module layout, dependency hierarchy, and design decisions.

M2M integration guide

Machine interface connection guide for external clients.

DTO generation

How Jakarta EE DTO objects are generated, JAXB configuration, and Catalog system.

3. External dependencies

The project builds on the NAV common schema project:

  • Common (hu.gov.nav.schemas.common2) - General NTCA 2.0 XSD definitions and Jakarta EE DTOs. The DCC API schemas and types build on this project, utilizing its string, type, customer, paging, entity, service, and authservice namespaces.

4. Architecture

The DCC API is a multi-module Maven project containing the schema definitions for the NAV DAC (Directive on Administrative Cooperation) M2M interface. The project defines three main layers:

  1. Schema layer (schema) - XSD schema definitions

  2. DTO layer (dto) - Jakarta EE Data Transfer Objects, generated from XSD schemas

  3. BOM layer (bom) - Bill of Materials for centralized dependency version management

4.1. Project structure

DCC-API
├── bom/
│   ├── bom-all/               # Full BOM (project + external dependencies)
│   └── bom-project/           # Project modules only BOM
├── schema/
│   ├── schema-auth/           # M2M Token API schema
│   ├── schema-dac9/           # DAC9 Global Tax API schema
│   └── schema-oecd-globe/     # OECD GLOBE Pillar Two third-party schemas
├── dto/
│   ├── dto-auth/
│   │   └── dto-auth-jakarta/  # Generated Jakarta EE DTOs from schema-auth
│   ├── dto-dac9/
│   │   └── dto-dac9-jakarta/  # Generated Jakarta EE DTOs from schema-dac9
│   └── dto-oecd-globe/
│       └── dto-oecd-globe-jakarta/  # Generated Jakarta EE DTOs from OECD GLOBE schema
└── docs/                      # Documentation

4.2. Module hierarchy

4.2.1. Schema modules

schema-auth

Contains the XSD schema for the M2M authentication token API.

schema-dac9

Contains the API XSD schema for DAC-9 services.

schema-oecd-globe

Contains the OECD GLOBE (Global Anti-Base Erosion) Pillar Two Information Return XML schemas. These are third-party XSD definitions published by the OECD, serving as the basis for content validation of DAC9 global minimum tax reports.

4.2.2. DTO modules

dto-auth-jakarta

Jakarta EE DTO classes generated from schema-auth XSD schemas using JAXB.

  • Dependencies:

    • hu.gov.nav.schemas.common2:dto-jakarta - Common NTCA 2.0 DTOs

    • hu.gov.nav.dcc.api:schema-auth - Auth schema definitions

dto-dac9-jakarta

Jakarta EE DTO classes generated from schema-dac9 XSD schemas using JAXB.

  • Dependencies:

    • hu.gov.nav.schemas.common2:dto-jakarta - Common NTCA 2.0 DTOs

    • hu.gov.nav.dcc.api:schema-dac9 - DAC9 schema definitions

dto-oecd-globe-jakarta

Jakarta EE DTO classes generated from schema-oecd-globe OECD GLOBE XSD schemas using JAXB. This module is standalone and does not use the Episode mechanism, as the OECD types are completely independent of the NTCA Common types.

  • Dependencies:

    • hu.gov.nav.schemas.common2:core-jakarta - Common NTCA 2.0 core module

    • hu.gov.nav.dcc.api:schema-oecd-globe - OECD GLOBE schema definitions

4.3. Dependency diagram

DCC API module dependency diagram

4.4. Namespace strategy

The project uses the following namespace hierarchy:

Namespace pattern Description

http://schemas.nav.gov.hu/NTCA/2.0/common/*

NTCA 2.0 common schemas (Common project)

http://schemas.nav.gov.hu/DCC/1.0/m2m/token/*

DCC M2M authentication schemas

http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/*

DCC M2M DAC9 schemas

urn:oecd:ties:globe:v2

OECD GLOBE Information Return main schema

urn:oecd:ties:isoglobetypes:v1

OECD ISO country, currency, and language code types

urn:oecd:ties:globestf:v5

OECD reusable types

The namespaces are organized under schemas.nav.gov.hu, with the DCC/1.0 version identifier, and the m2m prefix indicates the machine-to-machine communication nature.

4.5. Technology stack

Technology Version / Description

Java

17

Jakarta EE

JAXB 3.0 (Jakarta XML Binding)

Maven

Multi-module POM structure

JAXB plugin

org.jvnet.jaxb:jaxb-maven-plugin:4.0.9

JAXB extensions

Fluent API (jaxb2-fluent-api:3.0), Annotate (jaxb-plugin-annotate:4.0.8)

XSD Catalog

OASIS XML Catalog-based namespace resolution

Common schemas

hu.gov.nav.schemas.common2:2.0.0-rc.1 (NTCA Common)

5. M2M integration guide

This chapter contains the connection guide for the M2M (Machine-to-Machine) machine interface for external clients. The DCC API provides the following M2M functions:

  1. Authentication - Token request for M2M communication

  2. DAC9 report submission - Global minimum tax report management

General HTTP communication rules:

  • TLS 1.3 or later version is mandatory

  • Request/Response in XML format, unless the specific endpoint requires a different format.

  • Character encoding is UTF-8 in all cases.

  • Maximum accepted request size is 1 MB, unless the specific endpoint specifies a different size limit.

  • Compression in GZIP format. When compressed data needs to be sent, the fastest, least compressing, level 1 compression ratio should be applied ("gzip -1 [FILE]").

  • The server typically responds with sub-300ms response times.

  • The blocking timeout for synchronous calls is 5000 ms. Please handle response times exceeding the above value as timeouts on the client side! The absolute timeout value is 60 sec. If no response is received for a submission due to the 60-second timeout, it does not necessarily mean the submission failed.

  • The server receives time settings from a closed NTP server not accessible to the outside world. Client-side synchronization to the server time is not required, but optionally the following time synchronization is available: http://www.pool.ntp.org/zone/hu (NTP client required for connection).

  • Clients are expected to anticipate API version changes (with pre-announced, plannable times), and to consider the version number when processing requests and responses.

5.1. Integration process overview

M2M integration process

5.2. Authentication - Token request

The first step in M2M communication is requesting an access token through the Token API.

5.2.1. HTTP request

The access token is requested via an HTTP POST request with the following settings:

5.2.2. Request: M2MTokenRequest

The request is an extension of the NTCA AuthRequestType, which contains the standard authentication header, user data, and software identifier.

M2MTokenRequest XML example
<?xml version="1.0" encoding="UTF-8"?>
<ns3:M2MTokenRequest xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service" xmlns:ns2="http://schemas.nav.gov.hu/NTCA/2.0/common/authservice"
    xmlns:ns3="http://schemas.nav.gov.hu/DCC/1.0/m2m/token/tokenapi">
    <context>
        <requestId>019ce6a6-2a0c-7207-b3f4-cc8373579c7c</requestId>
        <timestamp>2026-03-13T10:02:55.37291704Z</timestamp>
    </context>
    <ns2:auth>
        <ns2:login>m2m_user_example</ns2:login> (1)
        <ns2:passwordHash cryptoType="SHA-512">12B03226A6D8BE9C6E8CD5E55DC6C7920CAAA39DF14AAB92D5E3EA9340D1C8A4D3D0B8E4314F1F6EF131BA4BF1CEB9186AB87C801AF0D5C95B1BEFB8CEDAE2B9</ns2:passwordHash> (2)
        <ns2:taxNumber>12345678</ns2:taxNumber> (3)
        <ns2:predecessorTaxNumber></ns2:predecessorTaxNumber> (4)
        <ns2:requestSignature cryptoType="SHA3-512">6498E406186580DA6403680FD3A6A008FD7F207CA2AFDE5885C38AC700A9A52A3BAADEE914FA0649DBBE103D2D6E99B1236DA403CDD5EF338245A4474770D591</ns2:requestSignature> (5)
    </ns2:auth>
    <ns2:requestVersion>1.0</ns2:requestVersion> (6)
    <ns2:headerVersion>1.0</ns2:headerVersion> (7)
</ns3:M2MTokenRequest>
1 The login tag contains the technical user’s name. The login name is randomly generated by the system when creating the technical user, with a length of 15 characters. The login tag is one of the authentication elements.
2 The passwordHash is the uppercase SHA-512 hash of the technical user’s password specified in the login tag. The literal password is set by the primary user who creates the technical user on the Online Invoice web interface. The passwordHash is one of the authentication elements. The only accepted value: SHA-512.
3 The taxNumber is the first 8 digits of the tax number of the taxpayer on whose behalf the technical user operates and to whom they belong. Only Hungarian tax numbers are accepted.
4 The predecessorTaxNumber, if provided, is validated to confirm whether it has a legal predecessor relationship with the taxpayer specified in the taxNumber tag. The legal predecessor relationship is checked recursively; indirect legal predecessors are also accepted. Providing the predecessorTaxNumber affects the business logic of operations.
5 The requestSignature is the client-generated signature of the message. Every request must have a requestSignature. The server performs its own requestSignature calculation based on the data in the request and only executes the request if the correct value can actually be derived from the stored and received data. The "requestSignature calculation" section provides information about computing the requestSignature. The only accepted value: SHA3-512.
6 The requestVersion indicates the request version; it is optional - if omitted, the system will use "1.0". Currently only the "1.0" value is accepted.
7 The headerVersion indicates the header version; it is optional - if omitted, the system will use "1.0". Currently only the "1.0" value is accepted.
requestSignature calculation

The requestSignature is one of the main elements of interface authentication. Its purpose is to prevent unauthorized parties from making changes in the system. The hash value is verified by the server side for every request of every operation, and the operation is only executed if the correct value can actually be derived from the stored and received data.

The requestSignature is calculated by concatenating the values of the following fields, in order:

  1. requestId value (in our case "019ce6a6-2a0c-7207-b3f4-cc8373579c7c")

  2. the timestamp tag value with the "yyyyMMddHHmmss" mask, in UTC time (in our case "20260313100255")

  3. the literal value of the technical user’s signing key (the value provided when creating the technical user). For this example, let its value be "ce-8f5e-215119fa7dd621DLMRHRLH2S"

The uppercase SHA3-512 hash result of the string concatenated in this order is the requestSignature value.

algorithm
requestSignature = SHA3-512(requestId + timestamp + signingKey).UPPERCASE()

requestSignature = SHA3-512(019ce6a6-2a0c-7207-b3f4-cc8373579c7c + 20260313100255 + ce-8f5e-215119fa7dd621DLMRHRLH2S).UPPERCASE()

requestSignature = SHA3-512(019ce6a6-2a0c-7207-b3f4-cc8373579c7c20260313100255ce-8f5e-215119fa7dd621DLMRHRLH2S).UPPERCASE()

requestSignature = 6498e406186580da6403680fd3a6a008fd7f207ca2afde5885c38ac700a9a52a3baadee914fa0649dbbe103d2d6e99b1236da403cdd5ef338245a4474770d591.UPPERCASE()

requestSignature = 6498E406186580DA6403680FD3A6A008FD7F207CA2AFDE5885C38AC700A9A52A3BAADEE914FA0649DBBE103D2D6E99B1236DA403CDD5EF338245A4474770D591

5.2.3. Response: M2MTokenResponse

Upon successful authentication, the response contains the access token and its expiration time.

M2MTokenResponse XML example
<?xml version="1.0" encoding="UTF-8"?>
<ns3:M2MTokenResponse xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service" xmlns:ns2="http://schemas.nav.gov.hu/NTCA/2.0/common/authservice"
    xmlns:ns3="http://schemas.nav.gov.hu/DCC/1.0/m2m/token/tokenapi">
    <context>
        <requestId>019ce66a-c965-74cd-9795-1102575b62b7</requestId>
        <timestamp>2026-03-13T08:58:04.006840049Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns3:accessToken>eyJhbGciOiJIUzI1NiIsInR5cC... JWT token</ns3:accessToken>
    <ns3:accessTokenExpiryAt>2026-03-13T13:59:07.478552281Z</ns3:accessTokenExpiryAt>
</ns3:M2MTokenResponse>
Table 1. Response fields
Field Description Type

accessToken

The access token value to be used for subsequent API calls

GenericIdType

accessTokenExpiryAt

The token expiration time (UTC, nanosecond precision)

GenericTimestampNanoType
The token must be renewed before the expiration time. Requests sent with an expired token will be rejected.

5.3. DAC9 GlobalTaxRequest report submission

With the access token in hand, the DAC-9 global minimum tax report can be submitted.

5.3.1. HTTP request

The report is submitted via an HTTP POST request with the following settings:

  • URL: https://api-dacentral.nav.gov.hu/dcc/v1/m2m/dac9/globaltax/report

  • HTTP method: POST

  • Headers:

    • Authorization: Bearer {access_token}

    • Content-Type: multipart/form-data

    • Accept: text/xml or application/xml

  • Body: Two-part multipart/form-data:

    • metadata - The XML representation of GlobalTaxRequest

      • Content-Type: application/xml

    • report - The report file (GloBE Information Return (Pillar Two) XML Schema).

      • Content-Type: application/octet-stream

      • If the file is not compressed, it must be sent as plaintext XML

      • If the file is compressed (gzip), the compressed raw binary stream must be sent.

      • The maximum allowable file size is 100 MB (both compressed and uncompressed). If the file is compressed, the size of the decompressed content must not exceed 250 MB.

    • Character encoding is UTF-8 in all cases

    • When submitting, the CRC32 checksum of the file content must also be provided in the reportChecksum field. If the file is compressed, the CRC32 value of the decompressed content must be provided.

5.3.2. Request: GlobalTaxRequest

<ns2:GlobalTaxRequest xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/globaltax/globaltaxapi">
    <context>
        <requestId>019ce6cd-394b-7622-9c01-6880b92f086d</requestId>
        <timestamp>2026-03-13T10:45:35.180339322Z</timestamp>
    </context>
    <ns2:compressedContent>false</ns2:compressedContent>
    <ns2:reportType>GLOBE_OECD_V1</ns2:reportType>
    <ns2:reportChecksum cryptoType="CRC32">639479525</ns2:reportChecksum>
</ns2:GlobalTaxRequest>
Table 2. Request fields
Field Description Required

compressedContent

true if the submitted content is compressed, false otherwise

Yes

reportType

The report type. Currently the only allowed value is: GLOBE_OECD_V1

Yes

reportChecksum

The checksum of the report (CryptoType). For compressed content, the checksum of the decompressed content must be provided.

Yes

5.3.3. Response: GlobalTaxResponse

<?xml version="1.0" encoding="UTF-8"?>
<ns2:GlobalTaxResponse xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/globaltax/globaltaxapi">
    <context>
        <requestId>019ce6cd-394b-7622-9c01-6880b92f086d</requestId>
        <timestamp>2026-03-13T10:45:35.180339322Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns2:globalTaxReportId>019ce6cd-4540-78a7-ac4f-5049465a1fa0</ns2:globalTaxReportId>
</ns2:GlobalTaxResponse>
Table 3. Response fields
Field Description

globalTaxReportId

The unique transaction identifier of the submitted report. This identifier is required to query the report status.

5.4. Report status query

The technical processing status of a submitted report can be queried based on the transaction identifier.

5.4.1. HTTP request

The report status is queried via an HTTP GET request with the following settings:

5.4.2. Response: ReportStatusResponse

<?xml version="1.0" encoding="UTF-8"?>
<ns2:ReportStatusResponse xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/globaltax/globaltaxapi">
    <context>
        <requestId>019cf6ac-b11c-74b6-8b8c-0832f6805328</requestId>
        <timestamp>2026-03-16T12:43:58.620345274Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns2:reportStatus>
        <ns2:status>VALID</ns2:status>
    </ns2:reportStatus>
</ns2:ReportStatusResponse>
Table 4. Possible statuses and actions
Status Action

UPLOADED

The report has been uploaded. Wait and query the status again.

VALIDATING

The report is being validated. Wait and query the status again.

VALID

The report is valid, technically processed successfully. No further action required.

INVALID

The report is invalid. Check the errorCode and anomaly fields to identify the cause of the error, then fix and resubmit the report.
Example: Invalid report response
<?xml version="1.0" encoding="UTF-8"?>
<ns2:ReportStatusResponse xmlns="http://schemas.nav.gov.hu/NTCA/2.0/common/service"
    xmlns:ns2="http://schemas.nav.gov.hu/DCC/1.0/m2m/dac9/globaltax/globaltaxapi">
    <context>
        <requestId>019cf6ac-b11c-74b6-8b8c-0832f6805328</requestId>
        <timestamp>2026-03-16T12:43:58.620345274Z</timestamp>
    </context>
    <resultCode>SUCCESS</resultCode>
    <ns2:reportStatus>
        <ns2:status>INVALID</ns2:status>
        <ns2:errorCode>INVALID_FILE</ns2:errorCode>
        <ns2:anomaly>
            <field>exampleField</field>
            <error>Invalid value in column 12, line 34</error>
            <lineNumber>34</lineNumber>
            <columnNumber>12</columnNumber>
        </ns2:anomaly>
        <ns2:anomaly>
            <error>Another error without line and column information</error>
        </ns2:anomaly>
    </ns2:reportStatus>
</ns2:ReportStatusResponse>

5.5. Java client example

Using the dto-auth-jakarta and dto-dac9-jakarta Maven modules, request-response objects can be handled directly from Java.

5.5.1. Maven dependencies

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>hu.gov.nav.dcc.api</groupId>
            <artifactId>bom-project</artifactId>
            <version>1.0.0-rc.2-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>hu.gov.nav.dcc.api</groupId>
        <artifactId>dto-auth-jakarta</artifactId>
    </dependency>
    <dependency>
        <groupId>hu.gov.nav.dcc.api</groupId>
        <artifactId>dto-dac9-jakarta</artifactId>
    </dependency>
</dependencies>

5.5.2. Token request assembly

import hu.gov.nav.schemas.dcc._1_0.m2m.token.tokenapi.M2MTokenRequest;
import hu.gov.nav.schemas.dcc._1_0.m2m.token.tokenapi.M2MTokenResponseType;

// Create token request (fluent API)
M2MTokenRequest tokenRequest = new M2MTokenRequest();
// ... set header, user, and software data

// Process response
M2MTokenResponseType response = // ... HTTP call result
String accessToken = response.getAccessToken();
OffsetDateTime expiryAt = response.getAccessTokenExpiryAt();

5.5.3. DAC9 report submission

import hu.gov.nav.schemas.dcc._1_0.m2m.dac9.globaltax.globaltaxapi.GlobalTaxRequest;
import hu.gov.nav.schemas.dcc._1_0.m2m.dac9.globaltax.globaltaxapi.GlobalTaxResponseType;
import hu.gov.nav.schemas.dcc._1_0.m2m.dac9.globaltax.globaltaxapi.ReportStatusResponseType;

// Report registration request
GlobalTaxRequest request = new GlobalTaxRequest();
request.setCompressedContent(true);
request.setReportType(ReportTypeType.GLOBE_OECD_V_1);
// ... set checksum

// Process response
GlobalTaxResponseType taxResponse = // ... HTTP call result
String reportId = taxResponse.getGlobalTaxReportId();

// Status query
ReportStatusResponseType statusResponse = // ... HTTP call result
FileStatusType status = statusResponse.getReportStatus().getStatus();

6. DTO generation

The DCC API project does not contain any hand-written Java source code. All Java classes (DTO – Data Transfer Object) are generated from XSD schemas at build time using the JAXB (Jakarta XML Binding) Maven plugin.

The generation uses the following technologies:

  • Jakarta EE JAXB 3.0 – XML-Java binding

  • XSD Catalog – Namespace resolution from Maven artifacts

  • JAXB plugin extensions – Fluent API and annotation handling

  • Episode files – Duplication-free generation of common types

6.1. DTO modules

Module ArtifactId Description

Auth DTO

dto-auth-jakarta

Jakarta EE DTOs from the Token API (e.g. tokenapi.xsd) schema

DAC9 DTO

dto-dac9-jakarta

Jakarta EE DTOs from the Global Tax API (e.g. globaltaxapi.xsd) schema

OECD GLOBE DTO

dto-oecd-globe-jakarta

Jakarta EE DTOs from the OECD GLOBE Pillar Two schemas (e.g. GLOBEXML_v1.0.xsd)

6.2. Generation process

Generation is performed using the org.jvnet.jaxb:jaxb-maven-plugin:4.0.9 plugin, executing the generate goal in the Maven build generate-sources phase.

6.2.1. Steps

  1. The plugin reads the all-in-one.xsd aggregator schema

  2. The OASIS XML Catalog (catalog.cat) resolves namespaces to the appropriate Maven artifacts

  3. The JAXB binding file (bindings.xjb) is applied

  4. Common types are sourced from Episode files (not regenerated)

  5. Generated Java classes are placed in the target/generated-sources/src/main/java directory

6.2.2. Generation configuration

<plugin>
    <groupId>org.jvnet.jaxb</groupId>
    <artifactId>jaxb-maven-plugin</artifactId>
    <version>4.0.9</version>
    <executions>
        <execution>
            <id>dcc-super</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <episodes>
                    <episode>
                        <groupId>hu.gov.nav.schemas.common2</groupId>
                        <artifactId>dto-jakarta</artifactId>
                    </episode>
                </episodes>
                <strict>false</strict>
                <catalog>src/main/resources/catalog/catalog.cat</catalog>
                <schemaIncludes>
                    <include>catalog/all-in-one.xsd</include>
                </schemaIncludes>
                <bindingIncludes>
                    <include>xjb/bindings.xjb</include>
                </bindingIncludes>
                <generateDirectory>
                    ${project.build.directory}/generated-sources/src/main/java
                </generateDirectory>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <verbose>true</verbose>
        <schemaDirectory>src/main/resources</schemaDirectory>
        <args>
            <arguments>-Xfluent-api</arguments>
            <arguments>-Xannotate</arguments>
        </args>
        <plugins>
            <plugin>
                <groupId>org.jvnet.jaxb2_commons</groupId>
                <artifactId>jaxb2-fluent-api</artifactId>
                <version>3.0</version>
            </plugin>
            <plugin>
                <groupId>org.jvnet.jaxb</groupId>
                <artifactId>jaxb-plugin-annotate</artifactId>
                <version>4.0.8</version>
            </plugin>
        </plugins>
    </configuration>
</plugin>

6.3. XSD Catalog system

The XSD Catalog operates according to the OASIS XML Catalog standard. The catalog.cat files map namespaces to Maven artifacts, enabling modular use of schemas.

6.3.1. Catalog entries (Example)

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

    <!-- NTCA 2.0 common schemas (Common project) -->
    <public publicId="http://schemas.nav.gov.hu/NTCA/2.0/common/string"
        uri="maven:hu.gov.nav.schemas.common2:schemas:jar::!/xsd/.../string.xsd" />
    <public publicId="http://schemas.nav.gov.hu/NTCA/2.0/common/type"
        uri="maven:hu.gov.nav.schemas.common2:schemas:jar::!/xsd/.../type.xsd" />
    <!-- ... additional NTCA namespaces ... -->

    <!-- DCC Auth schema -->
    <public publicId="http://schemas.nav.gov.hu/DCC/1.0/m2m/token/tokenapi"
        uri="maven:hu.gov.nav.dcc.api:schema-auth:jar::!/xsd/.../tokenapi.xsd" />

</catalog>

6.3.2. All-in-one aggregator schema

The all-in-one.xsd is an aggregator schema that imports all required namespaces as a single entry point for the JAXB generator:

<xsd:schema
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://catalog.schemas.nav.gov.hu/DCC/1.0/common/all-in-one">

    <!-- NTCA 2.0 common namespaces -->
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/string" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/type" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/customer" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/paging" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/entity" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/service" />
    <xsd:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/authservice" />

    <!-- DCC module-specific schema -->
    <xsd:import namespace="http://schemas.nav.gov.hu/DCC/1.0/m2m/token/tokenapi" />

</xsd:schema>

6.4. JAXB binding configuration

The bindings.xjb file contains the following global settings:

6.4.1. generateIsSetMethod

<jaxb:globalBindings generateIsSetMethod="true">

For optional fields, isSet*() methods are also generated, which can be used to check whether a given field has been set (with a value other than null).

6.4.2. Date/time type mappings

XSD type Java type Adapter class

xsd:date

java.time.LocalDate

LocalDateXmlAdapter

xsd:time

java.time.OffsetTime

UtcOffsetTimeXmlAdapter

xsd:dateTime

java.time.OffsetDateTime

UtcOffsetDateTimeXmlAdapter

The adapter classes are located in the hu.gov.nav.schemas.common2.core.adapter package (in the Common project’s dto-jakarta module).

6.5. Episode mechanism

Episode files ensure that where types use common NTCA 2.0 types (e.g. GenericIdType, BaseRequestType), they are not regenerated in every DTO module. Instead, the plugin references the hu.gov.nav.schemas.common2:dto-jakarta artifact’s Episode file, so only DCC-specific types are generated.

For example, the dto-oecd-globe-jakarta module does not use the Episode mechanism, as the OECD GLOBE types are completely standalone and independent of the NTCA Common types.

Episode configuration
<episodes>
    <episode>
        <groupId>hu.gov.nav.schemas.common2</groupId>
        <artifactId>dto-jakarta</artifactId>
    </episode>
</episodes>

6.6. JAXB plugin extensions

6.6.1. Fluent API (-Xfluent-api)

The jaxb2-fluent-api:3.0 extension generates fluent (chainable) setter methods:

// Standard JAXB
request.setCompressedContent(true);
request.setReportType(ReportTypeType.GLOBE_OECD_V_1);

// Fluent API
request.withCompressedContent(true)
       .withReportType(ReportTypeType.GLOBE_OECD_V_1);

6.6.2. Annotate (-Xannotate)

The jaxb-plugin-annotate:4.0.8 extension allows adding custom annotations to generated classes through the binding file.