Version 0.1 - Draft
KinML is a human-readable language for describing people and their relationships. It is designed to support incomplete, uncertain, and evolving information and to be authored directly by humans.
KinML prioritizes simplicity, linearity, and tolerance of ambiguity over strict validation.
KinML is designed to be:
- human-authored and human-readable
- tolerant of unknown or partial information
- line-oriented and append-friendly
- minimal in syntax
- renderer-agnostic
- easy to parse with a simple parser
Person: an individual, identified by a textual name.
Union: a relationship context between two or more people.
Child: a person associated with a union.
Annotation: free-form text attached to a person, union, or child.
Unknown person: a person whose identity is unknown, represented using ?.
The input is processed line by line.
Line order is significant.
Empty lines are ignored.
Leading and trailing whitespace on each line is ignored.
A comment line begins with #.
Comment lines are ignored.
The following characters have special meaning:
+ union operator
= child operator
| annotation marker
? unknown person marker
All other characters are treated as literal text.
A person is declared by a line containing a name.
Example:
Alex
A name is any non-empty text not starting with a reserved character.
Names MAY contain spaces.
Names are case-sensitive for display, but tools MAY normalize internally.
The token ? denotes an unknown person.
Unknown persons MAY be combined with additional text to disambiguate identity.
Examples:
?
? 1
? maternal
Alex ???
Identical unknown tokens refer to the same unknown person.
Different unknown tokens refer to different unknown persons.
A union is declared using the + operator.
Example:
Alex + Barbara
A union MUST contain at least two persons.
A union establishes a new relationship context.
Whitespace around + is optional.
Example:
Alex+Barbara
A child is declared using the = operator following a union.
Example:
= Charlie
A child declaration MUST follow a union.
The child is a person.
Multiple children MAY be declared for a single union.
An annotation line begins with |.
Example:
| Born 2002
An annotation applies to the immediately preceding entity.
Valid annotation targets are:
- a person
- a union
- a child
An annotation with no valid preceding entity is invalid.
Annotation text is opaque.
Parsers MUST NOT infer meaning from annotation content.
Tools MAY recognize annotation conventions.
Unions apply forward until a new union is declared.
Children apply to the most recent union.
Annotations apply only to the immediately preceding entity.
The same person MAY appear multiple times in the file.
Renderers MAY treat the first annotation of a union as a display label.
Renderers MAY vary visual styling based on annotation content.
Renderers MAY use file order as a layout hint.
Renderers SHOULD visually distinguish unknown persons.
These behaviors do not affect validity.
A parser MUST reject or report:
- a child declaration without a preceding union
- an annotation without a valid preceding entity
- a union with fewer than two persons
A parser MAY recover from errors where possible.
This specification defines the core language.
Extensions SHOULD prefer conventions and annotations over new syntax.
Backwards compatibility is a goal but not guaranteed prior to version 1.0.
Alex + Barbara
| Married 2001
= Charlie
| Born 2002
Charlie + Felicity
= Gertrude
?
| Unknown individual
This spec is intentionally conservative. Most semantic meaning is deferred to tooling and rendering layers.