Entity Specifications¶

This directory contains machine-readable specifications for all domain model entities, optimized for LLM agent consumption and code generation.

Purpose¶

These specifications serve as the authoritative source for: - API generation (REST, GraphQL) - XML Schema generation (XSD) - Validation rule generation - Client library generation

Structure¶

specs/
├── _meta/                      # Shared definitions and conventions
│   ├── naming-conventions.md  # Naming rules across formats
│   ├── relationship-types.md  # Standard relationship definitions
│   └── mermaid-cardinality.md
├── _generation/               # Code generation guidelines
├── types/                     # Data type definitions (version in filename)
│   ├── primitives/           # XML Schema built-in types (xs:)
│   │   └── primitives-1.0.md
│   ├── strings/              # Restricted string types (strings:)
│   │   └── strings-1.0.md
│   ├── dates/                # Date range types (dates:)
│   │   └── dates-1.0.md
│   ├── coordinates/          # Coordinate types (coordinates:)
│   │   └── coordinates-1.0.md
│   └── enums/                # Enumeration types (enums:)
│       └── enums-1.0.md
├── entities/                  # Entity specifications by level
│   ├── level2/               # Domain model level2
│   │   ├── type-registry.yaml
│   │   ├── dataset-1.0.md    # Entity specs with version in filename
│   │   └── ...
│   └── level2-ehds/          # EHDS extension (planned)
└── exchange/                  # Exchange specifications (transfer protocols)
    ├── metaplus/             # Exchange specs for Metaplus imports
    │   ├── type-registry.yaml
    │   ├── metaplus-transfer-1.0.md
    │   └── types/
    │       └── exchange-types-1.0.md
    ├── dataset-transfer/     # Exchange specs for DatasetCollection transfers
    │   ├── type-registry.yaml
    │   ├── dataset-collection-transfer-1.0.md
    │   └── types/
    │       └── exchange-types-1.0.md
    └── tenant-snapshot/      # Exchange specs for full tenant data snapshots
        ├── type-registry.yaml
        ├── tenant-snapshot-transfer-1.0.md
        └── types/
            └── exchange-types-1.0.md

URI Mapping¶

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

Spec Path	XML Schema URI
`types/strings/strings-1.0.md`	`https://schemas.rutdev.se/xsd/types/strings-1.0.xsd`
`types/dates/dates-1.0.md`	`https://schemas.rutdev.se/xsd/types/dates-1.0.xsd`
`entities/level2/dataset-1.0.md`	`https://schemas.rutdev.se/xsd/entities/level2/dataset-1.0.xsd`
`exchange/metaplus/metaplus-transfer-1.0.md`	`https://schemas.rutdev.se/xsd/exchange/metaplus/metaplus-transfer-1.0.xsd`

File Format¶

Each entity specification follows a consistent template:

YAML Front Matter¶

Contains entity metadata (name, version, namespace)

Metadata Block¶

Machine-parseable entity configuration (abstract, extends, API endpoint, etc.)

Properties Block¶

Structured property definitions with types, constraints, API flags.

Properties use PascalCase type names (prefix resolved automatically):

properties:
  - name: id_at_origin
    type: IdentifierToken
    required: true
    description: "Identifier at the source system. Used during import to determine if the entity exists (update) or is new (create). Must remain stable for the same entity."

  - name: description
    type: MultilingualText
    required: false
    description: "Explanation of the entity"

See entities/README.md for property format and types/type-registry.md for registry details

Relationships Block¶

Relationship definitions with cardinality and navigation rules

Constraints Block¶

Validation rules, uniqueness constraints, business rules

Examples¶

JSON and XML representations with complete and minimal examples

API Patterns¶

CRUD operations with endpoints, methods, and status codes

Reading Priority¶

For LLM Agents: Focus on YAML blocks (metadata, properties, relationships, constraints, api_operations)

For Humans: Read markdown descriptions, examples, and business context sections