Exchange Specifications¶

This directory contains machine-readable specifications for exchange documents (transfer protocols). Exchange specifications define the root elements and structure of XML instance documents used for data transfer.

Purpose¶

Exchange specifications serve as the authoritative source for: - XML Schema generation for transfer documents - Import/export document structure - Validation of exchange payloads - API request/response body definitions

Directory Structure¶

exchange/
├── README.md                      # This file
└── metaplus/                      # Exchange specs for metaplus
    ├── type-registry.yaml         # Type registry (extends entity types)
    ├── metaplus-transfer-1.0.md        # Exchange specs with version in filename
    └── types/                     # Exchange-specific complex types
        └── exchange-types-1.0.md  # Types with version in filename

Variant and Versioning¶

Exchange specifications follow the same variant/versioning pattern as entity specifications:

Variant: Matches the entity model variant (e.g., level2, level2-ehds)
Version: Matches the entity model version (e.g., 1.0)

This ensures that exchange documents reference compatible entity types.

URI Mapping¶

File paths map to XML Schema URIs (version extracted from filename):

Spec Path	XML Schema URI
`exchange/level2/import-batch-1.0.md`	`https://schemas.rutdev.se/xsd/exchange/level2/import-batch-1.0.xsd`

Formula:

specs/exchange/{variant}/{exchange}-{version}.md
  → https://schemas.rutdev.se/xsd/exchange/{variant}/{exchange}-{version}.xsd

Exchange Specification Format¶

Each exchange specification follows a consistent template:

YAML Front Matter¶

---
exchange: ExchangeName
root: true
---

Field	Required	Description
`exchange`	Yes	PascalCase name of the exchange
`root`	No	`true` if this is a root element (default: `false`)

Markdown Sections¶

Description¶

What the exchange document represents and its purpose.

Properties¶

Exchange-specific properties (same format as entity properties):

properties:
  - name: batch_id
    type: IdentifierToken
    required: true
    description: "Unique identifier for this batch"

  - name: created_at
    type: dateTime
    required: true
    description: "Timestamp when batch was created"

Elements¶

Child entity collections that this exchange contains:

elements:
  - name: concepts
    entity: entities:Concept
    maxOccurs: unbounded
    description: "Concepts included in this exchange"

  - name: populations
    entity: entities:Population
    maxOccurs: unbounded
    description: "Populations included in this exchange"

Field	Required	Description
`name`	Yes	Element name in snake_case
`entity`	Yes	Namespace-qualified entity reference (e.g., `entities:Concept`, `exchange:Meta`)
`maxOccurs`	No	Maximum occurrences (default: 1, use `unbounded` for lists)
`minOccurs`	No	Minimum occurrences (default: 0)
`description`	Yes	Human-readable explanation

Important: Entity references must be namespace-qualified using a prefix defined in the type registry. Common prefixes: - entities: - References entity types from specs/entities/{variant}/{version}/ - exchange: - References exchange-specific types from specs/exchange/{variant}/{version}/types/

Constraints¶

Validation rules, business constraints.

Type Registry¶

Exchange directories contain a type-registry.yaml that extends the entity type registry:

registry:
  # Standard types (same as entities)
  xsd:
    namespace: "http://www.w3.org/2001/XMLSchema"
  strings:
    path: "types/strings"
    version: "1.0"
  dates:
    path: "types/dates"
    version: "1.0"
  enums:
    path: "types/enums"
    version: "1.0"

  # Entity types (for referencing entity complex types)
  entities:
    path: "entities/level2"
    version: "1.0"

  # Exchange-specific types
  exchange:
    path: "exchange/level2/types"
    version: "1.0"

XSD Generation¶

Root Element Declaration¶

Exchanges with root: true generate a global element declaration:

<xsd:element name="ImportBatch" type="tns:ImportBatchType"/>

Properties Type¶

Same pattern as entity specifications:

<xsd:complexType name="ImportBatchPropertiesType">
    <xsd:sequence>
        <xsd:element name="batchId" type="strings:IdentifierToken"/>
        <xsd:element name="createdAt" type="xsd:dateTime"/>
    </xsd:sequence>
</xsd:complexType>

Entity Element Collections¶

The elements section generates typed references to entity list types:

<xsd:complexType name="ImportBatchType">
    <xsd:sequence>
        <xsd:element name="properties" type="tns:ImportBatchPropertiesType" minOccurs="0"/>
        <xsd:element name="concepts" type="entities:ConceptListType" minOccurs="0"/>
        <xsd:element name="populations" type="entities:PopulationListType" minOccurs="0"/>
    </xsd:sequence>
</xsd:complexType>

Example XML Instance¶

<?xml version="1.0" encoding="UTF-8"?>
<ImportBatch xmlns="https://schemas.rutdev.se/xsd/exchange/level2/import-batch-1.0.xsd">
    <properties>
        <batchId>batch-2024-001</batchId>
        <createdAt>2024-01-15T10:30:00Z</createdAt>
    </properties>
    <concepts>
        <concept>
            <properties>
                <idAtOrigin>concept-income</idAtOrigin>
                <name xml:lang="en">Income</name>
            </properties>
        </concept>
    </concepts>
    <populations>
        <population>
            <properties>
                <idAtOrigin>pop-sweden-2024</idAtOrigin>
                <name xml:lang="en">Swedish Population 2024</name>
            </properties>
        </population>
    </populations>
</ImportBatch>