feat: add extension framework, GET /capabilities, and segments extension#19
Open
johnf wants to merge 3 commits into
Open
feat: add extension framework, GET /capabilities, and segments extension#19johnf wants to merge 3 commits into
johnf wants to merge 3 commits into
Conversation
Make extensions first-class citizens of the specification (#17): - Add a curated extension registry: extensions are defined in the OpenAPI document with stable identifiers, schemas, and semantics, and extension properties are tagged with x-extension annotations. Unregistered experiments use an x- prefixed identifier. - Add a required GET /capabilities endpoint declaring the spec version the implementation targets, its implemented extensions, and its supported search facets. - Register segments as the first extension: an optional searchExtra.segments array of drill-down locations for full-text matches inside files, as a discriminated union of PageSegment (PDF pages) and AnnotationSegment (ELAN annotations). - Bump the spec version to 0.1.0 and start a changelog. - Rewrite the Extensions guide around the extension model, registry, feature detection, and client rules, keeping the legacy Oni-UI properties documented pending registration. - Announce the changes with a blog post.
johnf
force-pushed
the
feat/extensions-and-capabilities
branch
from
1881964 to
55368ca
Compare
Docusaurus 3.10 compiles blog .md files with MDX, which rejects HTML
comments, so <!-- truncate --> broke the build. Switch both posts to
the {/* truncate */} form, and give the announcement post a marker so
the untruncated-post warning stays quiet.
/capabilities answers three questions and only one is about extensions: implemented extensions, supported search facets, and the targeted spec version. Facet discovery and version reasoning were buried in the Extensions guide where portal implementers would not look for them. Add a Capabilities page under Getting Started owning the endpoint narrative, and slim the Extensions guide's feature-detection section to the extension key-lookup rule plus a link. The /capabilities operation description now points at the new page.
There was a problem hiding this comment.
Pull request overview
This PR updates the RO-Crate API specification to make extensions first-class and discoverable, introducing a required GET /capabilities endpoint plus the first registered extension (segments) for structured search-hit drill-down locations.
Changes:
- Add a required
GET /capabilitiesendpoint and correspondingCapabilitiesschema for feature detection (apiVersion, extensions, facets). - Introduce the registered
segmentsextension (schema + examples) as a discriminated union of segment types (page,annotation) undersearchExtra.segments. - Bump spec version to
0.1.0, add a changelog, and update documentation + blog announcements to describe the new extension model.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| openapi.yaml | Adds /capabilities, new schemas (Capabilities + segments), and updates examples/version to support extension discovery and segments. |
| docs/getting-started/extensions.md | Rewrites the Extensions guide around the registry + /capabilities feature detection model. |
| docs/getting-started/error-handling.md | Adjusts sidebar ordering to accommodate the new Capabilities guide. |
| docs/getting-started/capabilities.md | Adds a new guide describing /capabilities usage and response shape. |
| CHANGELOG.md | Introduces changelog and records the conformance-affecting 0.1.0 changes. |
| blog/2026-07-06-extensions-and-capabilities.md | Publishes announcement for extensions + /capabilities + segments. |
| blog/2024-12-20-api-announcement.md | Adds truncate marker for the initial announcement post. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+1078
to
+1080
| properties: | ||
| segments: | ||
| $ref: "#/components/schemas/SegmentsCapability" |
r-tae
reviewed
Jul 7, 2026
| @@ -6,3 +6,5 @@ tags: [paradisec, ldaca] | |||
| --- | |||
|
|
|||
| TODO: Document the first release of our API | |||
Member
There was a problem hiding this comment.
What is this file? Why is it dated 2024-12?
Collaborator
Author
There was a problem hiding this comment.
It is from way back when I first created the API docs. I'll create an issue to actually write this and update it
r-tae
reviewed
Jul 10, 2026
| page: 3 | ||
| highlight: | ||
| - "a wordlist of <em>West Alor</em> terms for kinship" | ||
| - type: "annotation" |
Member
There was a problem hiding this comment.
I think this should be named TimeAlignedAnnotation or similar. This should be appropriate for TextGrid (which, similar to Elan also uses tiers and timecodes), while avoiding other non-similar kinds of annotation (TEI annotations, interlinear glossing (I guess FieldWorks, I'm not educated on formats there))
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements #17.
What this does
Makes extensions first-class citizens of the specification:
Extension registry: extensions are defined in the OpenAPI document with stable identifiers, schemas, and semantics. Extension properties appear inline in core schemas as optional fields tagged
x-extension: <id>. Unregistered private experiments use anx-prefixed identifier.GET /capabilities(new required endpoint): every conformant implementation declares the spec version it targets (apiVersion), its implemented extensions (extensions— a map of extension id to configuration object), and its supported search facets (facets— a map of field name to configuration with an optional displaylabel).segments— the first registered extension: an optionalsearchExtra.segmentsarray on search hits carrying structured drill-down locations for full-text matches inside files, as a discriminated union ontype:PageSegment: 1-basedpagenumber plus highlight fragments (PDF matches)AnnotationSegment:tier(ELAN TIER_ID),startMs/endMsplus highlight fragments (transcription matches)Segments are optional, ranked by relevance, capped at an implementation-defined limit advertised as
maxSegmentsin/capabilities; clients MUST skip segments with unrecognisedtypevalues.Versioning: spec bumped 0.0.1 → 0.1.0 (a required endpoint is conformance-affecting),
CHANGELOG.mdstarted, and a blog post announces the framework.Docs: the Extensions guide is rewritten around the extension model, the curated registry, feature detection, and client rules; the legacy Oni-UI properties remain documented under "Legacy Extensions (Pending Registration)" — registering them is tracked in Register the legacy Oni-UI extensions in the extension registry #18.
Verification
pnpm lint(tsc, biome, redocly) passes with no rule suppressions — the Redocly lint validates the new examples against their schemas, including the spec's firstdiscriminator.pnpm buildsucceeds; the discriminator renders correctly on the generated Segment schema page, and the search response example shows both segment variants.Cross-repo consequences
Making
/capabilitiesrequired creates a build obligation for both implementations: nabu should advertisesegments(cap of 5) plus its facets, and arocapi needs the endpoint even without segments. The sibling PRDs in those repositories should be updated accordingly (upstream design source: paradisec-archive/nabu#1155).