integration guide

schema reference urls

all yettagam schemas are served from yettagam.net as permanent, versioned URLs. browse all 17 types in the schema browser, or use the types index for a machine-readable manifest.

key endpoints

type url patterns

every type definition follows a consistent url pattern:

https://yettagam.net/ytypes/{name}/{version}/{name}.ytype   # immutable permalink
https://yettagam.net/ytypes/{name}/latest.ytype              # mutable, latest version
https://yettagam.net/ytypes/{name}/                          # alias for latest.ytype

versioned urls are immutable permalinks — once published, their content never changes. the directory url /ytypes/{name}/ is an alias for latest.ytype, providing a clean, versionless reference for use in inherits_from and ytype fields.

schema linkage

yettagam uses a three-layer validation chain. each layer references the one above it, creating a chain of trust from meta-schema down to individual data objects.

yType meta-schema (/ytype/1.0.0/schema.json)
  validates ↓
yType definitions (.ytype files)
  $schema → meta-schema
  inherits_from → /ytypes/{parent}/
  schema section validates ↓
yObj instances (actual data objects)

the meta-schema defines what fields a valid yType must have — name, kind, schema, and so on. each .ytype file references the meta-schema via its $schema field, declaring itself as a conforming type definition. the schema section within each .ytype defines what instances (yObj) of that type look like — their required properties, types, and constraints. the inherits_from array references parent types via /ytypes/{name}/, which resolves to the latest version of that type.

using $schema references

creating a yType definition

to define a new type, create a .ytype file that references the meta-schema. the $schema field tells validators which meta-schema governs this definition. the schema section defines what instances of your type look like.

{
  "$schema": "https://yettagam.net/ytype/1.0.0/schema.json",
  "$version": "1.0.0",
  "$role": "type-definition",
  "name": "my-custom-type",
  "label": "My Custom Type",
  "description": "a custom type for my application",
  "kind": "concrete",
  "final": false,
  "singleton": false,
  "inherits_from": ["/ytypes/base/"],
  "definition": {},
  "schema": {
    "type": "object",
    "properties": {
      "custom_field": {
        "type": "string",
        "description": "a custom field for this type"
      }
    },
    "required": ["custom_field"]
  }
}

creating a yObj instance

a yObj is a concrete data object that conforms to a yType. reference the type via ytype using the directory url, which resolves to the latest version.

{
  "ytype": "/ytypes/image/",
  "ytype_label": "Image",
  "name": "my-photo",
  "label": "My Photo",
  "description": "a photograph",
  "graph": []
}

validating against yType

the schema section of each yType is a standard JSON schema. you can fetch the type definition at runtime and validate your yObj instances against it using any JSON schema validator.

python

import json, urllib.request

# fetch the type definition
type_url = "https://yettagam.net/ytypes/image/latest.ytype"
type_def = json.loads(urllib.request.urlopen(type_url).read())

# the schema section defines what instances look like
instance_schema = type_def["schema"]

# validate your yObj instance against it
import jsonschema
my_obj = {"name": "my-photo", "label": "My Photo", "description": "a photograph"}
jsonschema.validate(my_obj, instance_schema)

javascript

const res = await fetch("https://yettagam.net/ytypes/image/latest.ytype");
const typeDef = await res.json();
const instanceSchema = typeDef.schema;
// use ajv or similar to validate your yObj against instanceSchema

type inheritance

types reference parent types via the inherits_from array. each entry is a directory url like /ytypes/{name}/ that resolves to the latest version of the parent type. this creates a hierarchy of shared properties and constraints.

base (abstract)
  +-- ibase (abstract)
  |   +-- imedia (abstract)
  |       +-- image
  +-- media (abstract)
  |   +-- audio
  |   +-- video
  |   +-- document
  +-- commit
  +-- exhibition
  +-- list
  +-- venue
  +-- vr_device
  +-- url
  +-- platform_specific (abstract)
      +-- x_tweet
      +-- youtube_video

property resolution works by merging parent schema.properties with child schema.properties. when a child type defines a property that also exists in the parent, the child definition overrides the parent on conflict. this allows concrete types to specialize inherited fields while preserving the base structure.

MCP integration

the model context protocol (MCP) is a standard for AI agents to discover and interact with tools and data sources. yettagam schemas are designed to be machine-readable, enabling AI agents to discover schema definitions, understand data structures, and validate objects using yettagam types.

agent context endpoint

a machine-readable project context is available at:

GET https://yettagam.net/agent-context/

this returns structured metadata about the project, available schemas, and integration guidance — everything an AI agent needs to begin working with yettagam types.

example MCP tool definitions

the following tool definitions show how an MCP-compatible agent can interact with yettagam:

{
  "name": "yettagam_list_types",
  "description": "list all available yettagam type definitions",
  "inputSchema": {},
  "endpoint": "https://yettagam.net/ytypes/index.json"
}

{
  "name": "yettagam_get_type",
  "description": "get the full schema definition for a yettagam type",
  "inputSchema": {
    "type": "object",
    "properties": {
      "type_name": { "type": "string", "description": "name of the type" }
    },
    "required": ["type_name"]
  },
  "endpoint": "https://yettagam.net/ytypes/{type_name}/latest.ytype"
}

why structured schemas matter for AI

consistent data formats enable reliable data exchange between agents and systems. type safety prevents errors at the boundary between machine-generated and human-curated data. semantic relationships expressed through predicate groups enable knowledge graph construction — allowing agents to reason about the connections between objects, not just their individual properties.

contributing new types

yettagam is an open schema ecosystem. new types can be contributed by anyone following these steps:

1. create a .ytype file

   author a new type definition following the meta-schema at https://yettagam.net/ytype/1.0.0/schema.json. validate your file against the meta-schema before submitting.

2. include all required fields

   every yType definition must include these top-level fields: $schema, $version, $role, name, label, description, kind, final, singleton, inherits_from, definition, and schema.

3. submit a pull request

   open a pull request to https://github.com/MetariumProject/yettagam-net-website adding your file to ytypes/{name}/1.0.0/{name}.ytype and updating ytypes/index.json with the new type entry.