OpenAPI Spec Patches for Legba Compatibility

The OpenADR 3.1.0 specification (openadr3-specification/3.1.0/openadr3.yaml) declares itself as OpenAPI 3.0.0 format. Legba requires OpenAPI 3.1.x. Two changes are needed when copying the spec into this project's resources/openadr3.yaml.

1. Version declaration

The spec declares openapi: 3.0.0 but the content is compatible with 3.1.0. Legba validates the version string against the pattern ^3\.1\.\d+(-.+)?$ and rejects anything else.

-openapi: 3.0.0
+openapi: 3.1.0

2. exclusiveMaximum syntax

OpenAPI 3.0.x uses exclusiveMaximum: true (boolean) alongside a separate maximum value. OpenAPI 3.1.x (which aligns with JSON Schema draft 2020-12) uses exclusiveMaximum as the numeric value directly.

This affects the problem schema's status field (line ~2626):

           minimum: 100
-          maximum: 600
-          exclusiveMaximum: true
+          exclusiveMaximum: 600

3. payloadDescriptors discriminator mapping

The programRequest schema uses anyOf with a discriminator on objectType to distinguish eventPayloadDescriptor from reportPayloadDescriptor. The discriminator values (EVENT_PAYLOAD_DESCRIPTOR, REPORT_PAYLOAD_DESCRIPTOR) don't match the schema reference names, so Legba (via networknt/json-schema-validator) can't resolve them without an explicit mapping.

             discriminator:
               propertyName: objectType
+              mapping:
+                EVENT_PAYLOAD_DESCRIPTOR: '#/components/schemas/eventPayloadDescriptor'
+                REPORT_PAYLOAD_DESCRIPTOR: '#/components/schemas/reportPayloadDescriptor'

Without this, programs with payloadDescriptors (e.g. PRICE descriptors) are rejected by both request and response validation.

4. programName query parameter on GET /programs

A local extension that adds a programName query parameter to GET /programs, enabling direct lookup of a program by name (backed by the programName-index GSI on DynamoDB) instead of scanning the full collection. Tracks upstream proposal oadr3-org/specification#418.

       parameters:
         - name: targets
           ...
+        - name: programName
+          in: query
+          description: |
+            Filter results to programs whose programName matches exactly.
+            Local extension pending oadr3-org/specification#418 — enables
+            direct lookup without scanning the full program collection.
+          required: false
+          schema:
+            type: string
         - name: skip

Applying the patches

When updating resources/openadr3.yaml from a new spec release:

cp ../openadr3-specification/3.1.0/openadr3.yaml resources/openadr3.yaml
sed -i '' 's/^openapi: 3.0.0/openapi: 3.1.0/' resources/openadr3.yaml
sed -i '' '/maximum: 600/{N;s/maximum: 600\n          exclusiveMaximum: true/exclusiveMaximum: 600/;}' resources/openadr3.yaml

Why not fix upstream?

The upstream spec (openadr3-specification) targets broad compatibility and many tools expect OpenAPI 3.0.x. Changing it to 3.1.0 would break those consumers. These patches are local to the VTN server's copy of the spec.