OEAPI Profile and Consumer Repository

This repository provides an example of how an OEAPI profile and a consumer can be organised and used together.

Profiles and consumers are maintained outside the main OEAPI repository. They are stored as overlays on top of a specific OEAPI version. The resulting OpenAPI specification is generated by combining:

OEAPI base specification
+ profile overlay
+ consumer overlay
= generated OpenAPI specification for profile and consumer

Repository structure

dit is een voorbeeld van hoe de structuur van de repo kan worden opgebouwd. om gebruik te maken van de mergefunctie is deze opbouw aan te raden.

oeapi-profile-example/
├── README.md
├── base/
│   └── oeapi/
│       └── source/
└── profile-example/
    ├── README.md
    ├── profile.yaml
    ├── source/
    │   ├── spec.yaml
    │   ├── paths/
    │   ├── schemas/
    │   └── consumers/
    │       └── consumer-example/
    │           ├── consumer.yaml
    │           └── CourseConsumerExample.yaml
    └── generated/
        ├── spec.yaml
        ├── paths/
        ├── schemas/
        └── consumers/

Folders

The following sections explain the purpose of each folder.

base/oeapi

Contains the OEAPI base specification as a Git submodule.

This folder is read-only. Do not change files in this folder directly.

To upgrade to a newer OEAPI version, update the submodule reference and regenerate the profile specification.

profile-example

Contains the profile configuration, overlays, consumers and generated output for one profile.

profile-example/source

Contains the profile overlay files.

The structure mirrors the OEAPI source folder. Files in this folder are merged with the corresponding files from the OEAPI base specification.

Only files that differ from OEAPI should be added here.

profile-example/source/paths

Contains overlays for OEAPI path files.

Example:

source/paths/CourseInstance.yaml

profile-example/source/schemas

Contains overlays for OEAPI schema files.

Example:

source/schemas/Course.yaml
source/schemas/CourseProperties.yaml

profile-example/source/consumers

Contains consumer definitions.

Each consumer has its own folder.

Example:

source/consumers/consumer-example/
├── consumer.yaml
└── CourseConsumerExample.yaml

profile-example/generated

Contains the generated OpenAPI specification.

This folder is generated automatically and should not be committed or edited manually.

Profile configuration

Each profile has a profile.yaml file.

Example:

profileName: profile-example
profileVersion: v1.0

oeapi:
  oeapiPath: ../base/oeapi
  oeapiMinVersions:
    - v6.1
    - v7.0

consumers:
  - consumerName: consumer-example
    path: source/consumers/consumer-example

profileName

The name of the profile.

Example:

profileName: profile-example

profileVersion

The version of the profile.

Example:

profileVersion: v1.0

oeapi.oeapiPath

The relative path from the profile folder to the OEAPI base specification.

Example:

oeapi:
  oeapiPath: ../base/oeapi

oeapi.oeapiMinVersions

The minimum OEAPI versions supported by this profile.

Example:

oeapi:
  oeapiMinVersions:
    - v6.1
    - v7.0

A profile may support multiple OEAPI major versions. For each major version, the listed version is the minimum supported version.

consumers

The consumers used by this profile.

Example:

consumers:
  - consumerName: consumer-example
    path: source/consumers/consumer-example

A profile may reference one or more consumers.

Consumer configuration

Each consumer has a consumer.yaml file.

Example:

consumerName: consumer-example
consumerKey: consumer-example
consumerVersion: v2.1

oeapiMinVersions:
  - v6.1
  - v7.0

consumerName

The name of the consumer.

Example:

consumerName: consumer-example

consumerKey

The unique key of the consumer.

Example:

consumerKey: consumer-example

consumerVersion

The version of the consumer.

Example:

consumerVersion: v2.1

oeapiMinVersions

The minimum OEAPI versions supported by this consumer.

Example:

oeapiMinVersions:
  - v6.1
  - v7.0

A consumer may support multiple OEAPI major versions. For each major version, the listed version is the minimum supported version.

Overlay mechanism

The repository does not contain a full copy of the OEAPI specification.

Instead, it contains overlays. An overlay file describes only the differences relative to the OEAPI base specification.

The overlay merger combines:

base/oeapi/source
profile-example/source
profile-example/source/consumers

and writes the result to:

profile-example/generated

What an overlay does

An overlay can:

• add new values
• override existing values
• remove properties
• remove parameters
• extend schemas
• restrict schemas
• add profile-specific or consumer-specific definitions

Schema overlay example

Example:

required:
  - courseId
  - name
  - primaryCode
  - duration

properties:
  validFrom: null
  validTo: null

This overlay changes the OEAPI Course schema.

It does not redefine the full schema. It only describes the differences:

• courseId, name, primaryCode and duration are required
• validFrom is removed
• validTo is removed

Setting a property to null removes that property from the generated specification.

Consumer schema overlay example

Example:

properties:
  consumer:
    allOf:
      - $ref: './Consumer.yaml'
      - $ref: '../consumers/consumer-example/CourseConsumerExample.yaml'

This replaces or extends the generic OEAPI consumer property with a consumer-specific schema.

The consumer-specific schema is stored in the consumer folder.

Path overlay example

Example:

get:
  parameters:
    - name: expand
      _delete: true
  responses:
    '200':
      description: OK
      content:
        application/json:
          schema:
            $ref: '../schemas/Course.yaml'

This overlay changes the OEAPI path definition.

It removes the expand parameter and updates the response schema.

Setting _delete: true removes an item from an array, such as a parameter.

Generated metadata

During generation, profile and consumer metadata is added to the generated specification (spec.yaml).

Example:

x-profile:
  profileName: profile-example
  profileVersion: v1.0
  oeapiMinVersions:
    - v6.1
    - v7.0
  consumers:
    - consumerName: consumer-example
      consumerKey: consumer-example
      consumerVersion: v2.1
      oeapiMinVersions:
        - v6.1
        - v7.0

This makes it clear which profile, consumer and OEAPI versions are used in the specification.

Generate the specification

Run the overlay merger from the repository root.

The overlay merger is provided as an example utility. It is supplied without warranty of any kind and is used entirely at your own risk.

Example:

node overlay-merger.js profile-example

The generated files are written to:

profile-example/generated

Generated files should not be edited manually.

After generation, the specification can be bundled using the standard OEAPI tooling. If required, additional processing may then be performed before making the YAML specification publicly available.

Generation order

The generated specification is created in this order:

OEAPI base specification
Profile overlay
Consumer overlay
Generated OpenAPI specification
Bundled OpenAPI specification

Maintenance rules

Use these rules when maintaining the repository:

• keep OEAPI in base/oeapi as a Git submodule
• treat base/oeapi as read-only
• store only differences relative to OEAPI
• do not duplicate the complete OEAPI specification
• define consumers through a profile
• keep profile and consumer versions explicit
• generate the resulting specification from the base and overlays
• do not manually edit files in generated
• update the OEAPI submodule when upgrading to a newer OEAPI version

Summary

An OEAPI profile and consumer repository contains overlays on top of a specific OEAPI version.

The profile defines:

• which OEAPI version is used
• which consumers are included
• which profile-specific changes apply

A consumer defines:

• consumer metadata
• consumer-specific additions
• consumer-specific schema changes

The final OpenAPI specification is generated from:

OEAPI base + profile overlay + consumer overlay

This keeps the repository small, avoids duplication and makes it clear which OEAPI, profile and consumer versions were used.