yettagam improvement proposals

what is a YIP

a YIP (Yettagam Improvement Proposal) is the unit of change for the yettagam schema — the same idea as an EIP for Ethereum. Every addition or revision to the published schema (a new yType, a new version of an existing type, a meta-schema change) is proposed, reviewed, and recorded as a numbered, public YIP.

a schema change is typically discovered inside one application, proven there, then generalized and submitted as a YIP so the whole ecosystem can adopt it. a type that stays specific to one application does not need a YIP — it lives in that application. a YIP is for types that graduate to the shared schema.

ownership: a yType you keep inside your application is private intellectual property, owned by the organization that created it (all rights reserved by default). submitting a YIP is a deliberate, voluntary choice to publish that type into the open schema under yettagam's open license — there is no automatic graduation. the published schema is open; the private types and yObj libraries each organization builds remain their own.

read the process spec in YIP-0000, browse the YIP index, or start from the YIP template.

two versions: application vs schema

an application has two independent version axes, and keeping them separate is what makes safe, gradual schema evolution possible:

the compatibility contract, enforced by the registry's widening-only gate:

• within a major version, every YIP is widening-only — additive and backward compatible (new types, new optional fields, new enum values, loosened constraints). an app pinned to schema 1.x can adopt any 1.y with y ≥ x, at its own pace.
• a change that could invalidate a previously-valid yObj — removing/renaming a field, narrowing a type or enum, adding a required field or pattern, tightening minimum/maximum, closing additionalProperties, or dropping a parent — is breaking and requires a new major version of that type. old permalinks are immutable and served forever.

how running applications stay current

the schema is consumed offline-first and pinned: an application vendors a snapshot of the types it uses and records the schema version it is pinned to. To stay current it polls the manifest and upgrades on its own schedule — a schema update is a kind of live update, distinct from an app-code release.

GET https://yettagam.net/ytypes/index.json     # cheap, cacheable, CORS-open

compare the manifest version. if a newer same-major version exists, the app may refresh its mirror and adopt the new or updated types — a backward-compatible upgrade it can take whenever it likes. a new major version is an explicit migration the app opts into. The renderer is the component that adapts to the schema version of each yObj it is given, so one renderer can serve objects authored against several schema versions.

a push notification (webhook) on YIP merge is an optional convenience; the pull + version-pin model above is the dependency-free baseline.

submitting a YIP — people

1. prove it in an application first

   a type earns its place in the global schema by being useful somewhere real. note where it was proven and what makes it general.

2. generalize away application specifics

   remove assumptions that only fit one app — a site-specific classification scale becomes a generic optional field; a country-specific identifier becomes a generic registry_id + registry_scheme. Keep controlled vocabularies out of the schema (leave fields as open strings) so every site can bring its own.

3. author the files

   create the type per the integration guide, place it at ytypes/{name}/{version}/{name}.ytype with an identical latest.ytype, and add the entry to ytypes/index.json (alphabetical), bumping the manifest version.

4. open the YIP

   copy yip-template.md to yips/yip-XXXX.md, fill in motivation / specification / version impact / backward compatibility, and open a pull request against the repo. the maintainer assigns the number and merges.

submitting a YIP — AI agents

the machine-readable entry point is /agent-context/ (its yip block carries this protocol). the exact procedure, distilled from a real multi-type schema upgrade:

1. read current state

   fetch ytypes/index.json for the existing types and the current schema version, and the meta-schema at the version the index references.

2. classify the change

   new type (starts at 1.0.0) · widening of an existing type (minor bump, backward compatible) · breaking change (new major version, old permalink kept). Decide per type.

3. author each .ytype

   conform to the meta-schema: set $schema to the meta-schema permalink, include $version, $role, name, label, description, kind, final, singleton, inherits_from, definition (use {"predicateGroups": {}} if none), and a schema section. Write the versioned file and an identical latest.ytype.

4. validate before proposing

   every .ytype must validate against the meta-schema; each schema section must be a runnable JSON Schema (Draft 2020-12 check_schema); each concrete type must have a demo yObj that validates against it. For a revised type, verify the change is widening-only against the prior version (no removed/renamed field, no narrowed type/enum, no new required field, no tightened minimum/maximum/pattern, no additionalProperties closed) — otherwise it must be a new major version.

5. update the manifest and open the YIP

   add the entry to ytypes/index.json and bump its version; add yips/yip-XXXX.md (and an entry in yips/index.json); open a pull request. The maintainer reviews and merges; on merge the schema is live and the YIP is Final.

status lifecycle

Draft  ->  Review  ->  Last Call  ->  Final
                          \-> Withdrawn / Rejected

submitters open the proposal; the maintainer (metakovan, onemai foundation) reviews and merges. A Final YIP is immutable; superseding it requires a new YIP. The first schema YIP, YIP-0001, records the licensing and knowledge-graph types.