[Change request]: Service.supportedOperations[].path/supportedExpands[].path: format: uri-reference should be format: uri-template

[bartvriesema]

Organization

Maastricht University

Project

No response

Contact Details

b.vriesema@maastrichtuniversity.nl

Short description

source/schemas/Service.yaml declares both supportedOperations[].path and supportedExpands[].path as:

path:
  description: the path of the operation
  type: string
  format: uri-reference
  maxLength: 2048
  example: "/courses"

format: uri-reference means RFC 3986 URI-reference syntax, which does not permit literal {/} characters anywhere in the string — they're outside the unreserved/gen-delims/sub-delims character classes and would need percent-encoding to appear literally.

But both fields exist to report every operation/expand target a deployment supports, including operations with path parameters — and the only standard, unambiguous way to represent a parameterized route is the same templated-path syntax the spec's own paths: keys already use throughout oeapi.yaml (e.g. /academic-sessions/{academicSessionId}). A value like path: "/academic-sessions/{academicSessionId}/course-offerings" is therefore correct and expected, but fails format: uri-reference validation:

Value	format: uri-reference
/courses	valid
/courses/{courseId}	invalid

Version

v6

Usecase

automated schema validation of a GET / response (e.g. in CI, or any conformance-testing tool) reports a false failure for every operation that has a path parameter - which is most operations in the spec. No implementation can pass this part of the schema while also correctly reporting its own parameterized routes.

Which institutions support this change?

No response

Proposed solution

change format: uri-reference to format: uri-template on both fields. uri-template is itself a standard JSON Schema format value (Format-Annotation vocabulary, referencing RFC 6570 URI Template), designed for exactly this case — a string containing {placeholder} markers describing a family of URIs rather than one literal address. It accepts every legitimate path shape here, while still rejecting genuinely malformed values:

Value	format: uri-template
/courses	valid
/courses/{courseId}	valid
/courses/{courseId}/course-offerings/{courseOfferingId}	valid
/courses/{courseId (unclosed brace)	invalid
/courses/{{courseId}} (doubled braces)	invalid
/courses/{cour se Id} (space inside placeholder)	invalid

Requests and responses

No response

What is your question for the OOAPI work group?

No response