OASF API v0.6.0

[akijakya]

Hi everyone - on 2026-03-23 we are releasing OASF API v0.6.0, the culmination of the API refactor tracked in [Epic] OASF API improvements #417.

This release treats the recent API work as one cohesive improvement: cleaner endpoints, clearer identifiers, better taxonomy navigation, and better version discovery for multi-schema deployments.

The rollout affects all supported OASF versions on the official instance: https://schema.oasf.outshift.com.

Why this refactor was needed

The previous API shape had a few recurring pain points:

• confusion between class uid and the class attribute id, and between simple class names and hierarchical names
• endpoint overlap and legacy endpoints that were hard to justify
• taxonomy/category responses that were not aligned with class hierarchy
• version discovery endpoints that did not provide enough metadata for clients integrating across schema versions

API v0.6.0 addresses these directly.

Key changes in v0.6.0

1) Endpoint cleanup and simplification

Removed endpoints that were low-value or redundant, including validate_bundle, and consolidated schema access so clients can rely on /api/* routes consistently (for example, schema retrieval through /api/schema).

Why: reduce maintenance burden, lower surface area, and remove confusing alternatives.

2) Improved lookup semantics for taxonomy and class APIs

Lookup patterns now consistently support query-based filtering by both id and name on taxonomy and class APIs, instead of forcing path-only lookup variants. Object lookups were also simplified by standardizing on name-based access.

Why: this makes integrations less brittle and resolves ambiguity around identifiers, especially when clients only have one identifier form available.

3) Taxonomy/category endpoints now return nested taxonomy structures

<class_family>_categories responses now expose classes in hierarchical taxonomy form (instead of flat category grouping), and include focused fields intended for machine processing and UI navigation.

You will also see:

• category: true markers for category-only nodes
• deprecated: true markers for deprecated classes

Why: easier traversal for clients and LLM-based enrichment workflows, and clearer parent-child relationships in one response.

4) Better API version discovery metadata

Version endpoints now expose richer metadata so clients can reason about:

• schema_version
• server_version
• api_version
• canonical URLs for schema and API entry points
• default version resolution

Why: safer multi-version compatibility handling and easier automation when selecting target versions.

What this means for integrators

If your integration still assumes pre-v0.6.0 behavior, please update to:

1. Use /api/* canonical routes.
2. Prefer query filtering (id, name) where supported.
3. Parse nested taxonomy responses instead of flat category payloads.
4. Consume version metadata from /api/version and /api/versions for compatibility decisions.

Breaking-change context

This release rolls up the major API breaking changes introduced during the epic:

• #414 - taxonomy/category response redesign
• #426 - class API normalization and endpoint consolidation
• #428 - cleanup of redundant routes and API surface
• #430 - version API metadata and default-version behavior fixes

Endpoint before/after matrix

This table covers the endpoints impacted by the v0.6.0 refactor and how to migrate.

Before (pre-v0.6.0)	After (v0.6.0)	What happened	Why / migration note
GET /export/skills	GET /api/skills	export endpoint removed; API endpoint is canonical	Use /api/skills for detailed class payloads
GET /export/domains	GET /api/domains	export endpoint removed; API endpoint is canonical	Use /api/domains
GET /export/modules	GET /api/modules	export endpoint removed; API endpoint is canonical	Use /api/modules
GET /export/objects	GET /api/objects	export endpoint removed; API endpoint is canonical	Use /api/objects
GET /export/schema	GET /api/schema	Moved from Export to Schema API group	Update schema fetchers to /api/schema
GET /api/modules/:name	GET /api/modules?id=<id> or GET /api/modules?name=<name>	Path-specific lookup consolidated into query-based lookup	Prefer query filtering by id or name
GET /api/skills/:name	GET /api/skills?id=<id> or GET /api/skills?name=<name>	Path-specific lookup consolidated into query-based lookup	Prefer query filtering by id or name
GET /api/domains/:name	GET /api/domains?id=<id> or GET /api/domains?name=<name>	Path-specific lookup consolidated into query-based lookup	Prefer query filtering by id or name
GET /api/module_categories/:name	GET /api/module_categories?id=<id> or GET /api/module_categories?name=<name>	Parent selection moved to query params; response redesigned as nested taxonomy	Parse hierarchical classes tree; handle category / deprecated markers
GET /api/skill_categories/:name	GET /api/skill_categories?id=<id> or GET /api/skill_categories?name=<name>	Parent selection moved to query params; response redesigned as nested taxonomy	Parse hierarchical classes tree; handle category / deprecated markers
GET /api/domain_categories/:name	GET /api/domain_categories?id=<id> or GET /api/domain_categories?name=<name>	Parent selection moved to query params; response redesigned as nested taxonomy	Parse hierarchical classes tree; handle category / deprecated markers
GET /api/objects/:name	GET /api/objects?name=<name> (or GET /api/objects for full list)	Path lookup aligned with list/filter route	Use GET /api/objects?name=<name> for single-object retrieval
POST /api/translate/object/:name	POST /api/translate/object/:name	Route remains name-based while object retrieval moved to query style	Keep name-based object path for translate calls
POST /api/validate/object/:name	POST /api/validate/object/:name	Route remains name-based while object retrieval moved to query style	Keep name-based object path for validate calls
POST /api/validate_bundle/skill	Removed	Endpoint removed	Use POST /api/validate/skill
POST /api/validate_bundle/domain	Removed	Endpoint removed	Use POST /api/validate/domain
POST /api/validate_bundle/module	Removed	Endpoint removed	Use POST /api/validate/module
GET /api/version -> { "version": "..." }	GET /api/version -> schema/server/api metadata object	Response expanded	Update client parser to schema_version, server_version, api_version, url, api_url
GET /api/versions with minimal version/url pairs	GET /api/versions with per-version metadata + resolved default	Response expanded and default-selection behavior corrected	Update compatibility/version-selection logic accordingly

Rollout note

This is the API refactor milestone ahead of broader v1.0.0 direction discussed in the epic. Please test your clients against v0.6.0 behavior this week so we can quickly address migration issues before release.

If you find compatibility issues, open an issue with sample request/response payloads and the schema/API versions you are targeting.

[akijakya]

The new API version (0.6.0) has been deployed to https://schema.oasf.outshift.com.