Skip to content

Metadata.md

Latest commit

 

History

History
744 lines (575 loc) · 21.2 KB

Metadata.md

File metadata and controls

744 lines (575 loc) · 21.2 KB

FROG logo

🐸 FROG Metadata Specification

Definition of the required metadata section of .frog programs
FROG — Free Open Graphical Language

Contents

1. Overview

The top-level metadata section defines the descriptive identity of a FROG program.

It carries source-level information such as:

  • program identity,
  • human-readable description,
  • authorship and maintenance information,
  • version-tracking information,
  • search and discovery hints.

The metadata section is part of the canonical .frog source representation. It is required for a conforming canonical source file.

However, metadata is non-executable. It MUST NOT define, modify, or override execution semantics.

Execution behavior MUST be derived from the validated executable source representation of the program, centered on the public interface and the authoritative executable diagram, and interpreted according to the normative language semantics.

Runtimes, compilers, and other execution-facing systems MUST ignore metadata fields when determining executable meaning.

Version fields also remain separated by role:

  • metadata.program_version versions one program artifact,
  • top-level spec_version versions the source-format compatibility target of the .frog file,
  • the published specification corpus version is governed centrally in Versioning/Readme.md.
Metadata at a glance

metadata
   -> descriptive identity
   -> documentation-facing information
   -> search / discovery support

metadata
   != interface
   != diagram
   != execution semantics
   != source-format compatibility law
   != specification corpus version

2. Why Metadata Exists

A canonical source file needs more than executable structure. It also needs a stable descriptive layer that helps humans, repositories, IDEs, search systems, and documentation workflows understand what a FROG is.

The metadata section exists to provide that descriptive layer without contaminating executable meaning.

It makes the source artifact easier to:

  • identify,
  • document,
  • index,
  • search,
  • classify,
  • version and curate.

At the same time, it preserves a strict architectural rule: descriptive information must remain separate from executable meaning. 

Why metadata exists

Humans and tools need:
- a name
- a description
- descriptive context
- discovery hints
- program artifact tracking

Execution does not need:
- author name
- tags
- summary text
- license label
- timestamps
- program_version

3. Scope

This document specifies:

  • the role of the required top-level metadata section,
  • the structure of the metadata object,
  • the meaning of standard metadata fields,
  • validation rules for those fields,
  • compatibility and extensibility rules for tool-added metadata.

This document does not specify:

  • the public program interface,
  • the executable dataflow graph,
  • the optional front-panel composition,
  • IDE authoring preferences,
  • cache or derived artifacts,
  • runtime scheduling, typing, or execution semantics,
  • the top-level spec_version compatibility policy,
  • the published specification corpus version.
This document owns:
- descriptive source identity
- standard metadata fields
- metadata validation rules
- metadata extensibility boundaries

This document does not own:
- public API
- executable graph
- IDE recoverability state
- tooling cache
- runtime meaning
- source-format compatibility policy
- specification corpus version policy

4. Relation with Other Specifications

The metadata section belongs to the canonical source specification in Expression/. It is one of the required top-level source sections of a canonical .frog file.

Its boundary with related sections is as follows: 

Top-level source-section boundary

metadata    -> descriptive source identity and documentation
interface   -> public typed program boundary
diagram     -> authoritative executable graph
front_panel -> optional user-facing interaction layer
ide         -> optional IDE-facing authoring preferences and recoverability aids
cache       -> optional derived non-authoritative tooling data

In particular:

  • metadata does not define the public API of the FROG. That belongs to interface.
  • metadata does not define executable logic. That belongs to diagram.
  • metadata does not define front-panel composition. That belongs to front_panel when present.
  • metadata does not carry IDE recoverability or editor-state preferences. That belongs to ide.
  • metadata does not carry derived accelerators or regenerated artifacts. That belongs to cache.
  • metadata.program_version does not define source-format compatibility. That belongs to top-level spec_version.
  • metadata.program_version does not define the repository-wide published specification corpus version. That belongs to Versioning/Readme.md.
Non-executable boundary inside Expression/

metadata -> durable descriptive identity
ide      -> IDE-facing authoring preferences and recoverability aids
cache    -> derived tooling accelerators safe to delete and regenerate

Version boundary

metadata.program_version -> one program artifact revision
spec_version             -> source-format compatibility target
Versioning/Readme.md     -> published specification corpus version

5. Location in a .frog File

The metadata section is a required top-level JSON object inside the canonical .frog source file.

Minimal canonical source shape: 

{
  "spec_version": "0.1",
  "metadata": {},
  "interface": {},
  "diagram": {}
}

A larger canonical source file MAY additionally include optional top-level sections such as connector, front_panel, icon, ide, and cache. 

Canonical .frog structure

example.frog
├─ spec_version
├─ metadata     -> required descriptive source section
├─ interface    -> required public typed boundary
├─ diagram      -> required executable graph
├─ connector    -> optional reusable-node perimeter mapping
├─ front_panel  -> optional UI composition
├─ icon         -> optional node icon
├─ ide          -> optional IDE-facing preferences
└─ cache        -> optional derived tooling data

Rules:

  • metadata MUST exist in a canonical .frog source file.
  • metadata MUST be represented as a JSON object.
  • Execution-facing systems MUST ignore metadata when determining executable behavior.

6. Metadata Structure

A typical metadata object is: 

"metadata": {
  "name": "Add",
  "summary": "Simple numeric addition example.",
  "description": "Adds two floating-point numbers and returns the result.",
  "author": "Example Labs",
  "program_version": "1.0.0",
  "tags": ["math", "example"],
  "is_example": true,
  "created": "2026-03-05T10:00:00Z",
  "updated": "2026-03-05T12:00:00Z",
  "license": "Apache-2.0"
}

The standard minimal required fields are:

  • name
  • description

All other standard fields are optional unless a profile, repository policy, or toolchain contract explicitly requires them.

Tools MAY add additional metadata fields, provided that those fields remain non-executable and safely ignorable by execution-facing systems.

Metadata fields such as author, created, and updated are descriptive document-level fields. They do not replace fine-grain source provenance for individual nodes, edges, widgets, regions, or review actions. 

Metadata structure model

Required descriptive core
   -> name
   -> description

Optional descriptive enrichments
   -> summary
   -> author
   -> program_version
   -> tags
   -> example flag
   -> timestamps
   -> license
   -> additional non-executable descriptive fields

7. Field Definitions

7.1 name

Human-readable program name. 

"name": "Add"
  • MUST be present.
  • MUST be a string.
  • SHOULD be concise and descriptive.
  • SHOULD identify the program clearly within its project, package, or library scope.

7.2 summary

Short one-line description suitable for listings, search results, previews, or browser-style views. 

"summary": "Simple numeric addition example."
  • MUST be a string if present.
  • SHOULD be a single concise sentence.
  • SHOULD complement name rather than repeat it verbatim.

7.3 description

Longer descriptive text explaining what the FROG does. 

"description": "Adds two floating-point numbers and returns the result."
  • MUST be present.
  • MUST be a string.
  • SHOULD describe externally meaningful behavior rather than internal implementation details.
  • MAY contain multiple sentences.

7.4 author

Identifies the creator, maintainer, or owning organization. 

"author": "Example Labs"
  • MUST be a string if present.
  • MAY name an individual, a team, or an organization.
  • SHOULD be treated as descriptive information, not as an access-control mechanism.

7.5 program_version

Version identifier of the FROG program artifact itself. 

"program_version": "1.2.0"
  • MUST be a string if present.
  • SHOULD use a stable project-defined versioning convention.
  • Semantic versioning (MAJOR.MINOR.PATCH) is RECOMMENDED when appropriate.
  • MUST be interpreted as the revision of the authored FROG program artifact, not as the source-format compatibility version of the file.
  • MUST NOT be interpreted as the published specification corpus version.

The following distinction MUST remain explicit: 

metadata.program_version -> version of one FROG program artifact
spec_version             -> source-format compatibility target of the .frog file
Versioning/Readme.md     -> published specification corpus version

These three notions are related but not interchangeable.

7.6 tags

Keyword list for search, indexing, filtering, or example browsing. 

"tags": ["math", "signal", "example"]
  • MUST be an array of strings if present.
  • Each element SHOULD be a short keyword or short phrase.
  • Tags SHOULD avoid meaningless duplication.
  • Lowercase normalized tags are RECOMMENDED when practical.

7.7 is_example

Indicates whether the FROG is primarily intended as an example, tutorial artifact, or demonstration program. 

"is_example": true
  • MUST be a boolean if present.
  • Tools MAY use this field to populate example browsers or tutorial collections.

7.8 created

Creation timestamp of the source artifact or of the program record tracked by the owning workflow. 

"created": "2026-03-05T10:00:00Z"
  • MUST be a string if present.
  • ISO-8601 UTC format is RECOMMENDED.
  • This field is descriptive and MUST NOT be used to derive execution behavior.

7.9 updated

Timestamp of the last significant metadata or source update tracked by the owning workflow. 

"updated": "2026-03-05T12:00:00Z"
  • MUST be a string if present.
  • ISO-8601 UTC format is RECOMMENDED.
  • When both created and updated are present, updated SHOULD NOT represent an earlier instant than created.

7.10 license

Informational license identifier associated with the program or its distribution context. 

"license": "Apache-2.0"
  • MUST be a string if present.
  • SPDX identifiers are RECOMMENDED when applicable.
  • This field is informational metadata. It does not alter execution semantics.

8. Validation Rules

  • metadata MUST be present.
  • metadata MUST be a JSON object.
  • metadata.name MUST be present and MUST be a string.
  • metadata.description MUST be present and MUST be a string.
  • If present, metadata.summary MUST be a string.
  • If present, metadata.author MUST be a string.
  • If present, metadata.program_version MUST be a string.
  • If present, metadata.tags MUST be an array of strings.
  • If present, metadata.is_example MUST be a boolean.
  • If present, metadata.created MUST be a string.
  • If present, metadata.updated MUST be a string.
  • If present, metadata.license MUST be a string.

Unknown metadata fields:

  • MAY be present.
  • MUST NOT affect executable meaning.
  • MUST be ignored by runtimes and other execution-facing systems.

Validation of metadata is structural and descriptive. A metadata validation failure MUST NOT be interpreted as a dataflow execution rule by itself. 

Validation boundary

metadata validation
   -> checks descriptive structure

metadata validation
   != executable graph validation
   != runtime semantic interpretation
   != source-format compatibility validation

9. Extensibility and Boundary Rules

Tools, repositories, or organizations MAY extend the metadata object with additional descriptive fields.

Such extensions MUST remain:

  • non-executable,
  • safely ignorable by runtimes,
  • compatible with canonical source transparency.

Example: 

"metadata": {
  "name": "Example",
  "description": "Example FROG.",
  "organization": "Example Labs",
  "documentation_url": "https://example.com/docs"
}

However, transient authoring state SHOULD NOT be stored in metadata. That kind of information belongs in ide when it is source-carried authoring metadata, or in cache when it is derived and regenerable tooling data.

Authoring-origin evidence, AI-generation markers, signed issuer claims, and human-review attestations belong in ide.provenance when they are serialized with source. They SHOULD NOT be collapsed into metadata.author, because document-level authorship is not the same thing as per-object provenance or review acceptance. 

Boundary rule for non-executable data

Durable descriptive identity
    -> metadata

IDE-facing authoring preferences or recoverability
    -> ide

Derived, regenerable tooling accelerators
    -> cache

Metadata extensions SHOULD remain understandable as descriptive source information. They SHOULD NOT become a hidden transport for execution hints, private lowering directives, runtime policies, editor-only transient state, or source-format compatibility policy.

10. Examples

10.1 Minimal Metadata Example

"metadata": {
  "name": "Add",
  "description": "Adds two numbers."
}

10.2 Extended Metadata Example

"metadata": {
  "name": "PIDController",
  "summary": "Basic PID controller example.",
  "description": "Implements a proportional-integral-derivative controller.",
  "author": "Example Automation",
  "program_version": "1.2.0",
  "tags": ["control", "pid", "automation"],
  "is_example": true,
  "created": "2026-03-05T10:00:00Z",
  "updated": "2026-03-05T14:00:00Z",
  "license": "Apache-2.0"
}

11. Design Goals

  • Provide a stable descriptive identity for a FROG program.
  • Support documentation, indexing, search, and discovery.
  • Support authorship and version-tracking workflows.
  • Remain compatible with transparent canonical source representation.
  • Remain strictly non-authoritative for execution semantics.
  • Preserve a clean architectural boundary with interface, diagram, front_panel, ide, and cache.
  • Preserve a clean versioning boundary with top-level spec_version and centralized corpus-version governance.
Metadata should stay:

- descriptive
- durable
- transparent
- searchable
- ignorable for execution
- distinct from source compatibility law

Metadata should not become:

- executable
- IDE transient state
- cache payload
- hidden runtime policy
- hidden spec_version substitute
- hidden corpus-version substitute

12. Summary

The required metadata section provides descriptive source information about a FROG program. It defines identity and documentation-oriented information without changing executable meaning.

This preserves a clean long-term separation between:

  • descriptive source identity (metadata),
  • public program boundary (interface),
  • authoritative executable logic (diagram),
  • optional user-facing composition (front_panel),
  • optional IDE-facing authoring metadata (ide),
  • optional derived tooling data (cache),
  • program artifact versioning (metadata.program_version),
  • source-format compatibility versioning (top-level spec_version),
  • published specification corpus version governance (Versioning/Readme.md).
One-line mental model

metadata tells you what the FROG is
metadata does not tell the FROG how to execute
metadata.program_version does not tell the repository what specification version it is