> [!tldr] A homegrown system for organizing information > Note: in this note I'm calling the system SIGIL, but the note on [[Sigil]] is about the definition of the word. I named this SIGIL as a [[Backronym]] because it uses [[Sigil]]s a lot, and otherwise naming this was impossible. # SIGIL — Simple Interchange Grammar for Identity and Linking **An interoperability substrate for small information systems.** SIGIL is a lightweight protocol for representing identifiable things across plain-text, tabular, file-based, and other information systems. It defines persistent identity, common metadata, derivation, relationships, representation, and lifecycle semantics while allowing entities to remain in their native schemas and stores. SIGIL is intentionally small. It does not require a universal database, ontology, storage engine, query language, or application. ## 1. Anything may be an entity; nothing must be An entity is any thing for which persistent identity is useful. An entity may represent a note, record, file, person, concept, project, event, physical object, relationship predicate, or anything else. ## 2. Every entity has exactly one permanent `_id` `_id` is the canonical identity of the entity and is the only required field. It MUST remain stable for the lifetime of the entity and SHOULD contain no semantic information. ```yaml _id: K7x92p ``` Names, locations, types, content, relationships, and representations may change without changing `_id`. Entity IDs MUST NOT contain characters reserved by the SIGIL address grammar. At minimum, `@` and `.` are reserved for version and property addressing. Profiles or tooling MAY reserve additional characters when necessary. ## 3. The core sigils define data roles SIGIL uses a deliberately small sigil vocabulary. ```text field ordinary asserted domain data _field protocol or profile metadata ~field derived or non-authoritative data >field authoritative outbound relationship ``` For example: ```yaml _id: K7x92p _name: Puzzle Box status: active ~contains: - dog - bicycle >project: P9m31q ``` Sigils describe the role of a field without defining its domain-specific meaning. ## 4. Common metadata fields have defined meanings The core vocabulary includes: `_id` — permanent entity identity. The only required field. `_name` — preferred human-readable name. `_alias` — one or more alternate names which may refer to the entity. Aliases are lookup hints, not identity assertions, and need not be unique. `_type` — operational classification indicating how tooling may treat the entity. `_created` — wall-clock time at which the entity was created. `_updated` — wall-clock time at which the authoritative logical state of the entity last changed. `_body` — unstructured textual content associated with the entity. `_path` — location associated with the entity's native representation or represented resource. Additional metadata MAY be defined by future protocol versions or profiles. ## 5. Ordinary fields are asserted domain data An unsigiled field represents ordinary data asserted as part of the authoritative state of the entity. ```yaml distance: 5.2 activity: running ``` SIGIL does not claim that asserted information is objectively true. It distinguishes authoritative stored assertions from information explicitly marked as derived. ## 6. Derived information is replaceable A field beginning with `~` contains information produced through calculation, aggregation, inference, enrichment, transformation, lookup, or another derivation process. ```yaml ~contains: - dog - bicycle ``` Derived information is not a primary source of truth and SHOULD be treated as replaceable or recomputable. Changes to derived fields alone SHOULD NOT change `_updated`. SIGIL does not require distinctions between deterministic calculation, probabilistic inference, aggregation, or external enrichment. ## 7. `>` asserts an outbound relationship owned by its subject A field beginning with `>` asserts a directed relationship from the current entity to one or more other entities. The remainder of the field name is the relationship predicate. ```yaml >containedBy: K7x92p >about: - B8m21q - N2v84s ``` Conceptually: ```text thisEntity → containedBy → K7x92p thisEntity → about → B8m21q thisEntity → about → N2v84s ``` The subject owns the authoritative relationship. The target MUST NOT be required to store a corresponding authoritative inverse assertion. Incoming relationships are discovered through querying or indexing. A system MAY materialize a derived backlink: ```yaml ~<containedBy: - A4m82q ``` Such a field is only a potentially stale derived view and MAY be omitted, regenerated, or discarded. ## 8. Relationships are open-world and ontology-optional Relationship predicates are extensible and need not be declared in advance. A predicate MAY be only a locally meaningful label: ```yaml >inspiredBy: B8m21q ``` or it MAY resolve to a formally identified concept or entity with additional semantic definitions. A predicate may therefore itself have an `_id`, participate in SIGIL, or be associated with an external vocabulary or ontology such as SKOS, RDF Schema, or OWL. SIGIL does not require ontologies, predicate registration, reasoning, inference, domain/range validation, or any particular semantic vocabulary. Formal semantics are an optional layer above the relationship model, not a prerequisite for using it. ## 9. Relationship targets resolve to entity IDs The canonical target of a relationship is another entity's `_id`. ```yaml >containedBy: K7x92p ``` A profile MAY provide native reference syntax when it can resolve unambiguously to an entity ID. For example, an Obsidian profile may permit: ```yaml >containedBy: "[[Puzzle Box]]" ``` when that note resolves to an entity whose `_id` is `K7x92p`. Native filenames, Wikilinks, database keys, paths, or similar handles are locators used for resolution. They do not replace canonical identity. ## 10. The logical entity model is flat and has a canonical JSON interchange form An entity consists of named fields whose values are either: - scalar values, or - arrays of scalar values. Nested objects are not part of the common entity model. The canonical interchange representation is a flat JSON object. ```json { "_id": "K7x92p", "_name": "Puzzle Box", "_alias": ["2026 Puzzle", "Puzzle Project"], "status": "active" } ``` A collection of entities MAY be represented as JSONL, with one entity per line. The JSON representation defines the interoperable logical form. Implementations do not need to use JSON as their native storage format. ## 11. Profiles map native representations to the logical entity model A SIGIL Profile defines how entities are represented within a particular environment, such as Markdown, CSV, YAML, Obsidian, a file archive, or a domain-specific system. Profiles may define: - serialization syntax, - array and escaping conventions, - native reference syntax, - path interpretation, - body handling, - scalar type conversion, - additional metadata, - or other representation-specific behavior. For example, a CSV profile might represent an array using `|` as a separator and `\` as an escape character. A representation is conforming when it can be transformed unambiguously into the canonical entity model and back without losing information governed by SIGIL. Profiles MUST preserve the semantics of the core protocol. ## 12. Representation, storage, and identity are independent An entity may remain in its native schema and store and need not be migrated into a universal repository. A Markdown note may contain its own entity record. A tabular entity may exist as a row. A JPEG, person, physical object, or immutable file may instead be described by a separate record. `_body` provides the logical field corresponding to unstructured textual content. In a Markdown profile, it SHOULD correspond to document content outside metadata. `_path` identifies a native representation or represented resource but is not part of entity identity. Stores MAY define a portable root, and portable implementations SHOULD prefer paths relative to that root. ```yaml _path: assets/photos/IMG_4821.jpg ``` A store may therefore be copied, synchronized, replicated, or mounted elsewhere without changing entity identity. ## 13. Representation changes do not create entity changes Formatting, field ordering, serialization changes, or conversion between conforming representations do not change the logical state of an entity. `_updated` SHOULD change only when authoritative logical entity content changes. The same `_id` continues to identify the entity regardless of representation or storage location. ## 14. `_id@_updated` identifies a particular entity state A bare ID: ```text K7x92p ``` refers to the enduring entity. A qualified ID: ```text K7x92p@2026-08-26T11:14:00 ``` refers to the state associated with that `_updated` value. Sequential version numbers and retention of historical states are not required. ISO 8601 wall-clock timestamps are RECOMMENDED. Timezone information MAY be included but is not required. ## 15. Dot notation addresses an entity property A property of an entity may be addressed as: ```text K7x92p.length ``` A property of a specific historical state may be addressed as: ```text K7x92p@2026-08-26T11:14:00.length ``` The version qualifier precedes the property selector. If the entity or property cannot be resolved, lookup tooling SHOULD return NULL. Property addressing is a query and reference convention and does not alter entity identity. ## Address Grammar ```text id – The enduring entity. ``` ```text id@version – A particular state of the entity. ``` ```text id.property – A property of the entity. ``` ```text [email protected] – A property of a particular entity state. ``` ## Governing Principles **Identity is permanent. Everything else is an assertion about identity.** **Fields declare their semantic role through a minimal sigil vocabulary.** **Authoritative relationships live only on their subjects.** **The world is open: predicates and schemas may evolve without central registration, with or without a formal ontology.** **Derived information may be useful without being authoritative.** **Representations may differ; the logical entity must survive conversion.** **Stores may remain independent; interoperability does not require centralization.** --- # Appendix A — SIGIL Profiles *This appendix is non-normative.* The SIGIL core describes the logical entity model. Profiles describe how that model is expressed in particular environments. A profile might define conventions such as: ```text SIGIL JSON Profile SIGIL JSONL Profile SIGIL Markdown Profile SIGIL CSV Profile SIGIL Obsidian Profile SIGIL File Archive Profile ``` Profiles are expected to solve practical representation problems without expanding the core protocol. For example, a CSV profile could specify that: ```text one|two|three ``` represents an array of three strings, while: ```text one\|two|three ``` represents: ```json ["one|two", "three"] ``` with `\` escaping the following character. A Markdown profile could specify that frontmatter fields map to entity fields while Markdown content maps to `_body`. An Obsidian profile could additionally permit Wikilinks as local shorthand for relationship targets, provided they can resolve to canonical `_id` values. Profiles may also define scalar coercion, filename conventions, `_path` roots, or additional profile-specific metadata. The important compatibility boundary is simple: > **A conforming profile can import to and export from the canonical SIGIL entity model without losing protocol-defined information.** # Appendix B — SIGIL Tooling and Repositories *This appendix is non-normative.* SIGIL intentionally does not define how collections of entities must be stored, synchronized, queried, merged, indexed, or reasoned over. Those behaviors belong to tooling and repository layers built on top of the entity protocol. Possible SIGIL-aware tooling may provide: - entity lookup and resolution, - property lookup, - relationship and backlink queries, - format conversion, - indexing, - search, - derived-field generation, - aggregation, - validation, - ontology resolution, - reasoning, - repository synchronization, - replication, - merge and conflict handling, - entity forwarding or equivalence, - views over entities, - or archival/version retrieval. Repositories may also maintain information that operates with the entity system but is not represented as an entity. For example, a repository may maintain **tombstones** for deleted entity IDs so that deletion can propagate during synchronization or merging without allowing an older copy of the entity to be unintentionally restored. Similarly, repository tooling may define rules for entity merges, redirects, `sameAs` relationships, conflict resolution, or vocabulary shorthand. These mechanisms are intentionally outside the SIGIL core. The core describes **what an entity means**. Profiles describe **how an entity is represented**. Tooling and repositories describe **what systems do with entities**. **** # More ## Source - self