Reference

Everything udd can do is exposed as JSON under /api. The debug console is a client of this API and nothing more.

Requests and responses are application/json. There is no authentication: anyone who can reach the port has full control of the directory.

Object payload #

Endpoints that return an object use one shape:

{
  "id": "9f2c…",                 // GUID (identity)
  "parent": "a01b…",             // GUID or null (root only)
  "name": "Jack",
  "class": "user",
  "classId": "c3d4…",
  "system": false,
  "facets": ["described", "person", "securityPrincipal"],   // effective surface
  "dn": "CN=Jack,OU=Sales",      // derived
  "path": "/Sales/Jack",         // derived
  "hasChildren": false,
  "stage": "alive",              // stored lifecycle stage (alive/deleted/shredded)
  "effectiveStage": "alive",     // stage after apply-time aging
  "ghost": false,                // class definition not yet in this node's schema
  "existence": { …stamp… },      // the existence atom's stamp (creation + stage transitions)
  "placement": { …stamp… },      // the (parent, name) atom's stamp
  "usnChanged": 51,              // node-private change-scan index
  "referencedBy": [              // the back-reference index: who points here
    { "id": "77aa…", "path": "/Admins", "attribute": "member" }
  ],
  "attributes": [
    { "name": "member",
      "values": [
        { "value": "b7e1…",
          "meta": { "expiry": ["2027-01-01T00:00:00Z"] },   // only when present
          "refPath": "/Sales/Jack",                         // reference syntax only; null unless target alive
          "refState": "alive",                              // alive / deleted / shredded / missing
          "stamp": { …stamp… } }                            // this value atom's stamp
      ],
      "absent": [                                           // only when present
        { "key": "c9a2…", "stamp": { …stamp… } }            // stamped residue of a removed value
      ] }
  ]
}

refPath appears only on values of reference-syntax attributes: the target's current native path, or null if the reference dangles.

Every merge atom — existence, placement, each attribute value — carries a stamp, the replication record that decides merges:

{
  "version": 2,                          // bumped per originating write to this atom
  "at": "2026-08-14T04:01:12Z",          // originating wall-clock time
  "origin": "e8a2…",                     // originating invocation id
  "cert": { "invocation": "e8a2…", "usn": 51 },   // transfer certificate (enumeration coordinate)
  "localUsn": 51                         // node-private
}

absent lists absence atoms: values (or, for a single-valued attribute, the whole attribute — key: null) that were removed and persist as stamped residue so the removal can win future merges. Rewriting an attribute with an unchanged value does not restamp it; multi-valued value sets are unordered and render in canonical (set-key) order.

Objects under a derived repair additionally carry conflicted / orphaned / cycleBroken flags, plus effectiveName (the CNF display name) and effectiveParent where they differ from the stored facts; dn and path always render the effective view. Child summaries carry name (effective), ghost, and the three repair flags.

Endpoints #

Attribute names in URLs and bodies are caseless and accept wire names (Acme-badgeColor); the stored spelling is always the schema's canonical one.

Every mutating endpoint acknowledges only after the write is durable — a 200/201/204 means the disk holds it. Attribute values are capped at 1 MiB each (large blobs are a future side-store's job, not an atom's).

The schema summary #

GET /api/schema returns the compiled schema, sorted by name:

{
  "attributes": [ { "id", "name", "syntax", "singleValued", "matching", "aliases", "legalMeta" } ],
  "facets":     [ { "id", "name", "attributes": [ { "name", "required" } ] } ],
  "classes":    [ { "id", "name", "dnPrefix", "instantiable", "facets" } ],
  "extensions": [ { "id", "name", "targetClass", "facets" } ],
  "quarantined": [ { "id", "name", "reason" } ]
}

quarantined lists definitions excluded from the effective schema — replication can deliver a facet before its attributes. Compilation is total: it never fails, it quarantines what cannot join yet (with the reason) and lets it join automatically when its dependencies arrive. References to tombstoned definitions compile out instead (the facet keeps working minus its dead member). Originating schema writes are still strictly gated: a local write that would grow the quarantine is refused with schema-violation.

Errors #

Failures return {"error": "<code>", "message": "<human text>"} with:

The base schema is the set of system definitions every directory is born with: 26 attributes, 11 facets, and 11 classes — 48 objects in all, flat under /Configuration/Schema and immutable forever.

All new definitions live in namespaces; the unprefixed name space tabulated below is reserved. The base definitions are minted at domain creation by the first node, as its ordinary originating writes. There are no well-known GUIDs — a joining node receives everything by sync.

Attributes #

Notes: description is multi-valued (following the LDAP RFCs where they and Active Directory disagree). attachedFacets is engine-level — legal on every object regardless of surface, and the vehicle for instance facet attachment. Aliases are recorded on definitions but not yet used for lookup. expiry and required exist to serve as meta keys (on member and attributes respectively). instantiable (unset = true) marks classes users may instantiate. maxTimeApart and timeUntilShred are the domain's lifecycle knobs, in seconds, held on the /Configuration object itself: timeUntilShred is the restore window (default 30 days — past it a soft-deleted record hardens to a skeleton), maxTimeApart the purge horizon and future partition contract (default 180 days — past it tombstones purge entirely). networkAddress holds a machine's network endpoints — multi-valued because a DNS name, an IPv4, and an IPv6 address are legitimately concurrent addresses of one machine.

The endpoint syntax #

networkAddress uses the endpoint value syntax: host[:port], where the host is a DNS name, an IPv4 literal, or a bracketed IPv6 literal ([2001:db8::1]:6000), and an omitted port designates the well-known GIP port, 5390 (GIP — the General Interlink Protocol — is UD's intra-domain machine-to-machine protocol; the syntax ships today, the protocol does not yet). The grammar is deliberately strict, because a loose syntax can never be tightened once values persist:

• no schemes (quic://…) and no whitespace anywhere;
• DNS names are ASCII (IDN arrives as punycode), dot-separated labels of letters, digits, and interior hyphens, ≤ 63 bytes per label and ≤ 253 total, with no trailing dot;
• anything whose last label is all digits must be a valid IPv4 literal — 999.1.1.1 is refused rather than silently treated as a DNS name — and leading zeros in octets (historical octal) are refused;
• IPv6 must be bracketed, zone ids (%eth0) are refused;
• an explicit port is 1–65535 with no leading zeros.

Values compare caselessly as opaque strings: DC1.corp and dc1.CORP are the same set member, but dc1.corp and dc1.corp:5390 are two distinct values even though they designate the same place — set matching is literal; interpreting endpoints is the dialer's job.

The publicKey syntax #

machineKey uses the publicKey value syntax: <algorithm>:<hex>, where the only algorithm today is x25519 and the payload is exactly 64 lowercase hex characters (32 bytes) — one canonical spelling per key, compared exactly. This is the machine's GIP identity key: udd new mints the keypair at enrollment, keeps the private half in the data directory's machine-key file, and records the public half here, replicated like any other fact. The attribute is multi-valued so a future key rotation can hold old and new keys through an overlap window. The algorithm prefix is deliberate agility: a future signing key gets a new prefix, not a new syntax.

Facets #

Required-ness is enforced today only where compilation demands it (schema definitions must be born complete); enforcement for ordinary objects is pending.

machine is the surface for anything reachable on the network; both attributes are deliberately optional on it — a pre-staged machine that has not yet enrolled has neither an address nor a key. The computer class composes it, and udd new creates one computer object for the machine it runs on. (The class is not called machine because definitions are siblings under /Configuration/Schema, where names are unique regardless of kind — the facet holds that name.)

Classes #

The self-hosting anchor: the classDefinition object under /Configuration/Schema is an instance of itself; every other definition's kind resolves from there.

An instantiable class must carry a dnPrefix (compile-enforced); non-instantiable classes are engine-created only. /Configuration is the singleton configuration instance — its class composition is what makes the replication knobs writable there, and future config areas graft on via classExtension. Besides /Configuration/Schema, the base tree also contains /LostAndFound, a system OU born with the domain: the destination replication repairs derive orphans and broken cycles into (the domain root is a replication head from birth). It also contains /Domain Controllers, the default home for machine objects — a convention, not structure: nothing in UD locates domain controllers by path, and a machine object is free to live anywhere.

Object names #

An object's bare name must be:

• non-empty and at most 255 bytes,
• free of control characters,
• free of / (the native path separator),
• without leading or trailing whitespace.

Everything else — spaces, Unicode, =, , — is legal; DN composition escapes what needs escaping. These rules are deliberately strict: loosening a validity rule later is safe, tightening one is a data migration.

Caseless comparison (pinned) #

Sibling uniqueness, attribute-name lookup, path resolution, and caseless-matched value sets all compare under Unicode canonical caseless matching (Unicode §3.13): two strings are equal iff

NFD(casefold(NFD(a))) == NFD(casefold(NFD(b)))

So Jack = jack, STRASSE = Straße (ß case-folds to ss), and composed é = decomposed e + ́. Stored spellings are always preserved; the folding governs comparison only. This function is pinned: changing it once data persists would shift uniqueness invariants underneath stored data.

Distinguished names #

DNs compose leaf-first from typed components: CN=Jack,OU=Sales. The component type is the object's class's dnPrefix; the value is the bare name escaped per RFC 4514 — a backslash before any of " + , ; < > \ anywhere, before a leading space or #, and before a trailing space. The root object contributes nothing; its DN is the empty string.

Native paths #

The untyped address form: / followed by bare names joined with /, root-first — /Sales/Jack, resolving case-insensitively. The root's path is /. Because / is banned in names, paths are unambiguous.

Definition names and wire names #

Schema definition names (attributes, facets, classes, extensions) follow a stricter grammar than object names: a letter followed by letters or digits — camelCase by convention, and no hyphens, because the hyphen is the namespace separator. Namespace names additionally allow dots between segments (each segment a letter followed by letters or digits): Acme and reverse-DNS com.acme.tools are both legal, and reverse-DNS is the convention for anything redistributable — it makes accidental collisions between vendors nearly impossible. A namespaced definition's wire name is Namespace-name (Acme-badgeColor, com.acme.tools-badgeColor) — the single hyphen is unambiguous because neither side may contain one. Base definitions are unprefixed, and that unprefixed space is reserved forever.

The namespace names gip and ud (caselessly) are permanently reserved: they are GIP's service namespaces (gip/relay, ud/drs), and service names share the schema's namespace universe.

dnPrefix values follow RFC 4512 keystring grammar (a letter, then letters, digits, or hyphens).

CNF display names #

When replication merges two live siblings whose names fold equal, the earliest placement claim keeps the name and the later one displays as <stored name> CNF:<guid> (laddering (2), (3)… past pathological collisions). This is a derived view, not a rename: the stored name is untouched, the CNF form resolves in paths, and an ordinary rename dissolves it.

The reserved descriptor x #

The name x (caselessly) is permanently reserved and can never be defined as an attribute, facet, class, extension, or namespace name. UD reserves it as its untyped-lookup descriptor so that no schema element can ever collide with that use.