Skip to content

Code Generation Guidelines

This directory contains guidelines and rules for LLM agents to generate various artifacts from entity specifications.

Purpose

The entity specifications in specs/ serve as the single source of truth for the domain model. All implementation artifacts (code, schemas, APIs) should be generated from these specifications following the guidelines in this directory.

Generation Targets

Each guideline file defines rules for generating a specific type of artifact:

File Output Type Description Quick Ref
xml-schema.md XSD XML Schema definitions XSD_RULES_QUICK_REFERENCE.md ⚠️

⚠️ Note: XML Schema generation has strict rules to prevent anti-patterns. See the quick reference card.

Usage for LLM Agents

When generating code from entity specifications:

  1. Read the entity specification from specs/entities/{level}/{entity}-{version}.md
  2. Current primary level: specs/entities/level2/
  3. Read the data types from specs/types/
  4. Primitives: specs/types/primitives/primitives-1.0.md
  5. Strings: specs/types/strings/strings-1.0.md
  6. Dates: specs/types/dates/dates-1.0.md
  7. Coordinates: specs/types/coordinates/coordinates-1.0.md
  8. Enums: specs/types/enums/enums-1.0.md
  9. Read the appropriate generation guideline from this directory
  10. Follow the rules and templates defined in the guideline
  11. Apply naming conventions from specs/_meta/naming-conventions.md
  12. Generate the output according to the template
  13. Validate the output against the rules

Example Workflow

# For an LLM agent generating OpenAPI specs:
1. Read specs/entities/level2/population-1.0.md
2. Read specs/types/primitives/primitives-1.0.md (and other type files as needed)
3. Read specs/_generation/openapi-spec.md
4. Apply type mappings from guideline
5. Generate OpenAPI schema component
6. Add validation constraints as specified
7. Include descriptions from metadata

Generation Principles

1. Consistency

  • All outputs from the same specification must be consistent
  • Type mappings must follow defined rules
  • Naming must follow conventions

2. Traceability

  • Generated code must reference source specification
  • Include metadata (entity name, version, generated date)
  • Add comments linking back to specification

3. Validation

  • Implement all constraints from specification
  • Include runtime validation where applicable
  • Generate validation tests

4. Documentation

  • Auto-generate documentation from specifications
  • Include examples from specifications
  • Keep documentation in sync with code

5. Maintainability

  • Use templates for consistency
  • Support regeneration without breaking custom code
  • Clear separation between generated and custom code

Directory Structure

specs/
├── _generation/          # This directory
│   ├── README.md        # This file
│   ├── openapi-spec.md
│   ├── xml-schema.md
│   └── XSD_RULES_QUICK_REFERENCE.md
├── _meta/               # Metadata and conventions
│   ├── naming-conventions.md
│   ├── relationship-types.md
│   └── relationship-glossary.md
├── types/               # Data type definitions (version in filename)
│   ├── primitives/      # XML Schema built-in types
│   ├── strings/         # Restricted string types
│   ├── dates/           # Date range types
│   ├── coordinates/     # Coordinate types
│   └── enums/           # Enumeration types
└── entities/            # Entity specifications by level (version in filename)
    ├── level2/          # Base domain model
    └── level2-ehds/     # EHDS extension (planned)

URI Mapping

Directory paths map to XML Schema URIs:

Spec Path XML Schema URI
types/strings/strings-1.0.md https://schemas.rutdev.se/xsd/types/strings-1.0.xsd
entities/level2/concept-1.0.md https://schemas.rutdev.se/xsd/entities/level2/Concept-1.0.xsd

Versioning

  • Guidelines are versioned alongside specifications
  • Breaking changes in guidelines require specification version bump
  • Maintain backward compatibility when possible

Contributing

When adding new generation targets: 1. Create a new guideline file in this directory 2. Follow the template structure of existing guidelines 3. Include type mappings, templates, and examples 4. Update this README with the new target 5. Test generation with sample entities

See Also