Schemas API

Manage Schema.org-style reusable metadata schemas for nodes. Schemas define the expected structure of metadata.properties for specific node types.

Overview

Schemas allow you to:

Define structured metadata templates for node types
Validate node metadata against schemas
Share schemas publicly or keep them private to your app
Version schemas with URI-based resolution

Endpoints

GET /schemas

GET List available schemas.

curl -X GET "https://api.ofself.ai/api/v1/schemas" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-ID: user-123"

Query Parameters:

Parameter	Type	Description
`category`	string	Filter by category
`search`	string	Search schema names, descriptions, and URIs
`scope`	string	`public` or `private`
`owner`	string	`system` or `user` — filter by ownership
`recommended`	boolean	Filter to schemas flagged as recommended by developer
`ids`	string	Comma-separated schema IDs to fetch specific schemas
`used_by_me`	boolean	Only return schemas used by the current user's nodes
`include_json_schema`	boolean	Include the full JSON Schema definition (default: `false`)
`limit`	integer	Max results per page (default: 50, max: 100)
`offset`	integer	Pagination offset (default: 0)

Visibility rules:

System schemas: Always visible to all users
Public schemas (scope='public'): Visible to all users
Private schemas (scope='private', private_to='user'): Only visible to the owner
App-private schemas (scope='private', private_to='app'): Only visible to the creating third-party app

GET /schemas/:schema_id

GET Get a specific schema by ID.

curl -X GET "https://api.ofself.ai/api/v1/schemas/schema-uuid" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-ID: user-123"

Query Parameters:

Parameter	Type	Description
`resolve`	boolean	Resolve parent schema if `extends` is set (default: `false`)
`include_json_schema`	boolean	Include the JSON Schema definition (default: `true`)

GET /schemas/uri/:schema_uri

GET Resolve a schema by URI (with optional version).

curl -X GET "https://api.ofself.ai/api/v1/schemas/uri/ofself.ai/meeting-notes?version=2" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-ID: user-123"

If no version is specified, returns the latest version.

POST /schemas

POST Create a new schema.

curl -X POST "https://api.ofself.ai/api/v1/schemas" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-ID: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meeting Notes",
    "description": "Schema for meeting note nodes",
    "category": "productivity",
    "recommended_node_type": "meeting_notes",
    "recommended_meaning_level": "CONTEXT",
    "scope": "public",
    "json_schema": {
      "type": "object",
      "properties": {
        "attendees": { "type": "array", "items": { "type": "string" } },
        "duration_minutes": { "type": "integer" },
        "action_items": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["attendees"]
    }
  }'

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Schema name
`description`	string	No	Schema description
`category`	string	No	Category for grouping
`recommended_node_type`	string	No	Suggested node_type when using this schema
`recommended_meaning_level`	string	No	Suggested meaning_level
`scope`	string	No	`public` (default) or `private`
`private_to`	string	No	`user` or `app` (required when scope is `private`)
`schema_uri`	string	No	Custom URI identifier (auto-generated from name if omitted)
`extends`	string	No	Parent schema ID to inherit properties from
`recommended_by_developer`	boolean	No	Flag schema as recommended (default: `false`)
`schema_metadata`	object	No	Arbitrary metadata to attach to the schema
`json_schema`	object	Yes	JSON Schema definition for metadata.properties

Response: 201 Created

PUT /schemas/:schema_id

PUT Update a schema (creates a new version).

curl -X PUT "https://api.ofself.ai/api/v1/schemas/schema-uuid" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-ID: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated schema",
    "json_schema": { ... }
  }'

DELETE /schemas/:schema_id

DELETE Soft-delete a schema.

curl -X DELETE "https://api.ofself.ai/api/v1/schemas/schema-uuid" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-ID: user-123"

POST /schemas/:schema_id/validate

POST Validate metadata against a schema.

curl -X POST "https://api.ofself.ai/api/v1/schemas/schema-uuid/validate" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-ID: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "attendees": ["Alice", "Bob"],
      "duration_minutes": 30
    }
  }'

Response: 200 OK

{
  "valid": true,
  "errors": []
}

Or if invalid:

{
  "valid": false,
  "errors": ["'attendees' is a required property"]
}

GET /schemas/categories

GET List available schema categories.

curl -X GET "https://api.ofself.ai/api/v1/schemas/categories" \
  -H "X-API-Key: your-api-key" \
  -H "X-User-ID: user-123"

Using Schemas with Nodes

When creating nodes, you can reference a schema to ensure metadata conforms to the expected structure:

# Create a node with schema-validated metadata
response = requests.post(
    "https://api.ofself.ai/api/v1/nodes",
    headers={"X-API-Key": API_KEY, "X-User-ID": USER_ID},
    json={
        "title": "Weekly Team Standup",
        "node_type": "meeting_notes",
        "meaning_level": "DATA",
        "graph_view": "identity",
        "schema_id": "meeting-notes-schema-uuid",
        "metadata": {
            "properties": {
                "attendees": ["Alice", "Bob", "Charlie"],
                "duration_minutes": 15,
                "action_items": ["Review PR #42", "Update docs"]
            }
        }
    }
)

Overview​

Endpoints​

GET /schemas​

GET /schemas/:schema_id​

GET /schemas/uri/:schema_uri​

POST /schemas​

PUT /schemas/:schema_id​

DELETE /schemas/:schema_id​

POST /schemas/:schema_id/validate​

GET /schemas/categories​

Using Schemas with Nodes​