ORGF

Open data format for organizational structures and any hierarchical model

A universal, open format for describing hierarchical models, their blocks, and tags. It also supports a model-wide value metric and unit for consistent digital analysis.

Download source code and license Download Adizes organizational design example

FORMAT SPECIFICATION

The ORGF source code is open.

Open on GitHub

reference:
  format: "ORGF 1.0.0"
  syntax: "YAML|UTF-8 without BOM"

  sections_fixed:
    orgformat: "string|required"
    reference: "section|optional"
    meta: "section|required"
    model: "section|optional"
    root: "block|required"
    hierarchy: "root.children[*].children[*]..."

  meta:
    title: "string|max250|optional"
    author: "string|max250|optional"
    rights_holder: "string|max250|optional"
    copyright: "string|max500|optional"
    license: "string|max120|optional"
    created: "string|optional|YYYY-MM-DD/ISO 8601"
    updated: "string|optional|YYYY-MM-DD/ISO 8601"
    status: "draft/final/archived|optional"

  model:
    name: "string|max250|optional"
    desc: "string|max1000|optional"
    value_label: "string|max80|optional|one_value_type_per_model"
    value_unit: "string|max40|optional|one_value_unit_per_model"

  block:
    name: "string|max250|optional|empty_allowed"
    desc: "string|max500|optional"
    value: "number|optional|own_value_only"
    pic: "section|optional"
    pic.set: "emoji/lucide/feather/simple-icons/iconify|required_if_pic"
    pic.name: "string|required_if_pic"
    tags: "array[string|max80]|optional|default:[]"
    hidden: "boolean|optional|default:false"
    branch_orientation: "auto/horizontal/vertical|optional|default:auto"
    style:
      fill: "default/#HEX|optional|default:default"
      contour: "default/solid/dashed/dotted/double|optional|default:default"
      contour_width: "default/regular/bold|optional|default:default"
    relation:
      line: "default/solid/dashed/dotted|optional|default:default"
      line_width: "default/regular/bold|optional|default:default"
      color: "default/#HEX|optional|default:default"
    children: "array[block]|optional|default:[]"

  authoring_rules:
    - "one_file=one_model"
    - "hierarchy=children"
    - "no_id_parent_order"
    - "empty_blocks_allowed"
    - "tags=plain_classifiers_not_key_value"
    - "desc=short_human_note_not_data_dump"
    - "style_relation=custom_overrides_only"
    - "tag_colors_not_stored_in_orgf"
    - "value_one_type_per_model"
    - "value_one_unit_per_model"
    - "value_on_block_is_own_value_only"
    - "value_totals_are_computed_not_stored"
    - "reference_if_present=complete_unmodified_canonical_copy_published_for_declared_orgformat_version_at_https://github.com/orgformat/orgf/releases"
    - "hidden=true_on_a_block_requires_hidden=true_on_every_descendant"

  normalization:
    unknown_fields: remark
    invalid_values: default
    over_limit: truncate
    invalid_yaml: reject
    invalid_structure: reject

  normalization_rules:
    - "missing_optional=default"
    - "unknown_fields=remark"
    - "invalid_values=default"
    - "over_limit=truncate"
    - "normalization=view_only_not_source_mutation"
    - "hidden_branch_inconsistency=remark_not_reject"
    - "normalization_propagates_hidden=true_to_all_descendants"

CORE PRINCIPLES

An open format for describing, sharing, and integrating hierarchical models

ORGF keeps the model portable and understandable, so it can move between people, tools, and systems without being locked into one interface.

UNIVERSALITY

One logic for any hierarchy

Use the same format for organizational structures, catalogs, classifiers, reference data, knowledge trees, and other nested models — without domain-specific required fields.

READABILITY

A YAML file people can read

The model remains understandable beyond an interface: open it, inspect it, and edit it as a meaningful description of the structure.

TRANSPARENCY

Structure without hidden IDs

Hierarchy is expressed directly through children, without technical identifiers or parent relationships hidden from the model author.

INTEGRATION

Exchange data beyond one interface

Share models with other teams, use them in data-to-diagram workflows, and integrate ORGF into your own systems and processors.

VALUE

One value model across the hierarchy

Set a numeric value on blocks and a unit for the model; totals are computed from the structure for consistent analysis.

INDEPENDENCE

Free to use and develop

ORGF is not tied to a particular editor, cloud, or vendor platform. Use it, extend it, and build your own IT solutions around it.

The model author defines its license

ORGF is an open and free format. The rights, license, and terms for a specific model are declared by its author in the model metadata.