Agentic Schema Definition - NinjaStack Docs
Description: Schema-first agentic backend framework documentation

Skip to content

# Agentic Schema Definition (ASD)

The ASD is NinjaStack's schema language — a typed, composable definition of your entire data model, agent configuration, and domain boundaries.

## Schema Structure

    classDiagram
        class AgenticSchema {
            +str project_name
            +list~EntitySchema~ entities
            +list~RelationshipSchema~ relationships
            +list~DomainSchema~ domains
        }
        class EntitySchema {
            +str name
            +StorageEngine storage_engine
            +list~FieldSchema~ fields
        }
        class FieldSchema {
            +str name
            +FieldType field_type
            +bool primary_key
            +bool indexed
            +FieldConstraint constraints
            +EmbeddingConfig embedding
        }
        class DomainSchema {
            +str name
            +list~str~ entities
            +AgentConfig agent_config
        }
        class RelationshipSchema {
            +str name
            +str source_entity
            +str target_entity
            +RelationshipType type
            +Cardinality cardinality
        }
        AgenticSchema --> EntitySchema
        AgenticSchema --> RelationshipSchema
        AgenticSchema --> DomainSchema
        EntitySchema --> FieldSchema

## Entities

Entities map to tables (SQL), collections (Mongo), nodes (Graph), or vector stores.

    from ninja_core.schema.entity import EntitySchema, FieldSchema, FieldType, StorageEngine

    book = EntitySchema(
        name="Book",
        storage_engine=StorageEngine.SQL,
        fields=[
            FieldSchema(name="id", field_type=FieldType.UUID, primary_key=True),
            FieldSchema(name="title", field_type=FieldType.STRING, indexed=True,
                        constraints=FieldConstraint(min_length=1, max_length=500)),
            FieldSchema(name="price", field_type=FieldType.FLOAT,
                        constraints=FieldConstraint(ge=0.0)),
        ],
    )

### Field Types

Type | Python Mapping | Description
--- | --- | ---
`STRING` | `str` | Short text
`TEXT` | `str` | Long text (supports embedding)
`INTEGER` | `int` | Whole numbers
`FLOAT` | `float` | Decimal numbers
`BOOLEAN` | `bool` | True/False
`DATETIME` | `datetime` | Timestamp
`DATE` | `date` | Date only
`UUID` | `UUID` | Unique identifier
`JSON` | `dict` | Arbitrary JSON
`ARRAY` | `list` | Lists
`BINARY` | `bytes` | Binary data
`ENUM` | `str` | Constrained values

### Embedding Config

Fields can be configured for vector embedding:

    FieldSchema(
        name="text",
        field_type=FieldType.TEXT,
        embedding=EmbeddingConfig(
            model="text-embedding-3-small",
            dimensions=1536,
            chunk_strategy="paragraph",
        ),
    )

## Relationships

Three types of relationships between entities:

    from ninja_core.schema.relationship import RelationshipSchema, RelationshipType, Cardinality

    # Hard FK relationship
    RelationshipSchema(
        name="order_customer",
        source_entity="Order",
        target_entity="Customer",
        relationship_type=RelationshipType.HARD,
        cardinality=Cardinality.MANY_TO_ONE,
        source_field="customer_id",
        target_field="id",
    )

    # Semantic similarity
    RelationshipSchema(
        name="similar_reviews",
        source_entity="Book",
        target_entity="Review",
        relationship_type=RelationshipType.SOFT,
        cardinality=Cardinality.MANY_TO_MANY,
    )

    # Graph edge
    RelationshipSchema(
        name="authored_by",
        source_entity="Book",
        target_entity="Author",
        relationship_type=RelationshipType.GRAPH,
        cardinality=Cardinality.MANY_TO_ONE,
        edge_label="AUTHORED_BY",
    )

## Domains

Domains group entities under a single expert agent:

    from ninja_core.schema.domain import DomainSchema
    from ninja_core.schema.agent import AgentConfig, ReasoningLevel

    catalog = DomainSchema(
        name="Catalog",
        entities=["Book", "Review"],
        agent_config=AgentConfig(
            model_name="gemini-2.5-flash",
            reasoning_level=ReasoningLevel.MEDIUM,
            temperature=0.7,
        ),
    )

## Serialization

The full schema serializes to `.ninjastack/schema.json`:

    from ninja_core.serialization.io import save_schema, load_schema

    save_schema(schema, ".ninjastack/schema.json")
    loaded = load_schema(".ninjastack/schema.json")