Ion codec for Morphir IR: checkpoint 1, v3 document shape

[DamianReeves]

Ion codec for Morphir IR

Checkpoint 1. This note decides the Ion document for IR v3, including values. IR v4 is the next slice.

The local copy of this note lives in .dev/ and is not committed. The shared copy is the finos/morphir discussion named in the checkpoint log below.

Checkpoint log

Checkpoint	Scope	Discussion
1	v3 document, two layouts, DSL annotations, types	#938
2	A spec may be split into several specs for one package or one module	#938
3	Specs read package::spec and module::spec. The name is the only group key	#938
4	Inline modules, types, and values merge with the matching top-level specs	#938
5	Dependencies are package::spec under the same merge rules. Empty arrays are omitted	#938
6	ionVersion in the morphir block, SemVer, omitted means latest	#938
7	Member specs use public::spec::typeAlias. Package and module stay grouping headers	#938
8	opaque, derived, and alias are modifiers in front of type	#938
9	custom is a modifier in front of type as well	#938
10	v3 values are public::def::value and public::spec::value. Bodies are S-expressions	#938

Decisions

1. The codec round-trips the IR. v3 is specified first. v4 is the next major slice. A v3 reader rejects a v4-only node.
2. A reader accepts two layouts and builds the same IR from either. A writer can emit either. Collapse and expand are inverses.
3. The datagram is the reading layout. The header is one struct, each package, module, type, and value is its own top-level struct, and morphir_footer::{} ends the document.
4. The record is one morphir:: struct. Packages hold modules, and modules hold types and values. It is the collapsed datagram.
5. Ion annotations read as a small DSL. A definition is access, then role, then kind: public::def::alias::type. A member specification uses the same slots: public::spec::opaque::type. opaque, derived, alias, and custom are modifiers in front of type. A specification is the public face, so its access is public. Package and module stay grouping headers: package::spec and module::spec.
6. An Ion annotation is the symbol before ::. A Morphir annotation is the annotation list on a specification. v3 specifications in this model do not carry that list. The name is reserved so v4 does not reuse it.
7. Names are canonical strings. morphir/SDK:basics#int is a fully qualified name. basics is a module name. int is a local name. A v3 path array is rebuilt from the canonical string.
8. formatVersion is the release string 3.0.0. v3 accepts kind: library only.
9. Type expressions use the compact string and the annotated forms in v3 type expressions. A v3 value body is an S-expression, as specified in v3 values.
10. A classic attribute payload is the attributes field. Writers omit it when the payload is the empty list. Readers treat a missing field as that empty list.
11. An author may write several package::spec structs with the same name, or several module::spec structs with the same package and name. A package::spec may also carry optional modules. A module::spec may carry optional types and values. The reader concatenates the inline lists with the matching top-level specs, in document order, into the one specification the IR stores. There is no separate group field. A def module is not split. A repeated def module name is rejected.
12. A writer omits an array that is allowed to be empty when it is empty. A reader treats the missing array as empty. This covers dependencies, modules, types, values, typeParams, constructors, args, and arguments.
13. The Ion document is its own contract. ionVersion in the morphir block is a SemVer 2.0 string and starts at 0.1.0-draft.1. It is separate from IR formatVersion. A missing ionVersion means the latest version this reader implements. Writers emit the field. Parsing uses the semver crate, not a hand-written version type.
14. A v3 value definition is public::def::value or private::def::value. A v3 value specification is public::spec::value. The body is an S-expression whose first symbol names the IR node. Apply is binary. A bare int, float, true, false, symbol, (), or [] is the compact form in the tables below. Writers omit an attribute struct when the payload is [].

Why two layouts

The datagram matches a streaming read. The codec already walks a distribution as a header, then one dependency, then one module, then the end. Each top-level struct can become one of those events without holding the rest of the file.

The record is the same information nested as a tree. Tools that read one Ion value can load it. Collapse is the bridge from the datagram to that tree.

JSON and YAML do not need the record in order to exist. Either Ion layout is read into the IR, and the existing JSON and YAML writers emit their documents from that IR. Collapse does not itself produce JSON. What it does provide is one tree whose shape follows the IR, which is the shape those writers already walk. A transform that never builds the IR would still have to map Ion annotations onto JSON tags, and map value S-expressions onto the classic value arrays.

Annotation grammar

A definition and a member specification use the same order. The role is def or spec.

Position	Symbols	When it appears
Access	public, private	A definition's access. A member specification is always public
Role	def, spec	Definition or specification
Kind	module, value, or a modifier plus type	The noun

alias::type, opaque::type, derived::type, and custom::type replace the single tokens typeAlias, opaqueType, derivedType, and customType. opaque::type and derived::type occur as specifications. A v3 definition is module, alias::type, custom::type, or value.

A package or module specification is a grouping header. The noun comes first and there is no access annotation.

Position	Symbols	When it appears
Kind	package, module	The group
Role	spec	The node is a specification

public::def::alias::type:: is a public type-alias definition. public::spec::opaque::type:: is an opaque type on a public face. public::spec::derived::type:: is a derived type specification. package::spec:: opens a dependency package. module::spec:: opens a module specification. The header annotation is morphir. The footer annotation is morphir_footer. Those two are document markers and do not take def or spec.

Ion contract version

ionVersion versions the Ion spelling. formatVersion versions the IR inside it. The two fields stay separate. IR formatVersion keeps the support table [3.0.0,3.1.0),[4.0.0,4.1.0). ionVersion follows SemVer is the default contract versioning scheme.

This contract is new, so it starts at 0.1.0-draft.1. A draft matches only that exact string. There is no released 0.1.0 yet, so the supported set is =0.1.0-draft.1. When a release exists, a reader accepts the current released major, the previous released major, and the exact drafts it lists. On 0.y.z the minor acts as the major, so 0.1.x stays compatible and 0.2.0 is a break. A reader ignores a member it does not understand unless critical names it.

A missing ionVersion means the latest version that reader implements. Today that is 0.1.0-draft.1. Writers still emit the field. A string that is not canonical SemVer, or a version outside the supported set, is rejected. The Rust reader parses it with semver::Version.

morphir::{
  ionVersion: "0.1.0-draft.1",
  formatVersion: "3.0.0",
  kind: library,
  packageName: "example/finance",
}

The same field sits on the record. The footer does not repeat it.

Reader dispatch

A datagram starts with morphir::, continues with zero or more definition structs, and ends with morphir_footer::{}. A footer is required. A truncated stream is invalid.

A record is a single morphir:: value and has no footer. Further values after a record are invalid.

v3 datagram

Writers emit the header, then each dependency package, then that package's modules, types, and values, then the distribution's own modules, types, and values, then the footer.

A missing package field means the distribution package. A type or a value always carries module. A reader rejects a type or value whose module was not declared. A repeated type name or value name in one module is rejected. A repeated package::spec name, or a repeated module::spec name in one package, is another part of the same specification and is accepted. List order inside the IR follows stream order.

morphir::{
  ionVersion: "0.1.0-draft.1",
  formatVersion: "3.0.0",
  kind: library,
  packageName: "example/finance",
}

package::spec::{
  name: "morphir/SDK",
}

module::spec::{
  package: "morphir/SDK",
  name: "basics",
}

public::spec::opaque::type::{
  package: "morphir/SDK",
  module: "basics",
  name: "int",
}

public::spec::opaque::type::{
  package: "morphir/SDK",
  module: "basics",
  name: "bool",
}

public::def::module::{
  name: "Eligibility",
  doc: "Credit eligibility.",
}

public::def::alias::type::{
  module: "Eligibility",
  name: "Decision",
  typeExp: "morphir/SDK:basics#bool",
}

public::def::custom::type::{
  module: "Eligibility",
  name: "Result",
  typeParams: ["a", "b"],
  access: public,
  constructors: [
    { name: "Ok", args: [ { name: "value", type: "a" } ] },
    { name: "Err", args: [ { name: "reason", type: "b" } ] },
  ],
}

morphir_footer::{}

access inside custom::type is the constructor group. The public annotation is the type's own access. v3 has both.

doc is omitted when the classic documented string is empty. A reader uses the empty string when doc is absent.

v3 record

Collapse groups the datagram by package and module, drops package and module, and drops the footer.

morphir::{
  ionVersion: "0.1.0-draft.1",
  formatVersion: "3.0.0",
  kind: library,
  packageName: "example/finance",
  dependencies: [
    package::spec::{
      name: "morphir/SDK",
      modules: [
        module::spec::{
          name: "basics",
          types: [
            public::spec::opaque::type::{ name: "int" },
            public::spec::opaque::type::{ name: "bool" },
          ],
        },
      ],
    },
  ],
  modules: [
    public::def::module::{
      name: "Eligibility",
      doc: "Credit eligibility.",
      types: [
        public::def::alias::type::{
          name: "Decision",
          typeExp: "morphir/SDK:basics#bool",
        },
        public::def::custom::type::{
          name: "Result",
          typeParams: ["a", "b"],
          access: public,
          constructors: [
            { name: "Ok", args: [ { name: "value", type: "a" } ] },
            { name: "Err", args: [ { name: "reason", type: "b" } ] },
          ],
        },
      ],
    },
  ],
}

Expand is the reverse. Children of a dependency package receive package equal to that package name. Children of the distribution package omit package. Types and values receive module.

v3 type expressions

A string that is a canonical fully qualified name is a reference with no arguments. A string that is a canonical local name is a variable. Any other string is rejected.

Node	Spelling
Variable	"a" or variable::{ name: "a" }
Reference	"morphir/SDK:basics#int" or reference::{ name: "morphir/SDK:list#list", arguments: ["a"] }
Tuple	tuple::[ "morphir/SDK:basics#int", "morphir/SDK:string#string" ]
Record	record::{ fields: [ { name: "score", type: "morphir/SDK:basics#int" } ] }
Extensible record	extensibleRecord::{ variable: "r", fields: [ { name: "email", type: "morphir/SDK:string#string" } ] }
Function	function::{ parameterType: "morphir/SDK:basics#int", returnType: "morphir/SDK:string#string" }
Unit	unit::{}

A function type is binary. A list type is a reference to morphir/SDK:list#list. A bare list is a tuple. Writers use the compact string when the node has no attributes and the compact string can say the node. Attributes, when present, force the expanded struct.

alias::type carries typeParams and typeExp. opaque::type carries typeParams. derived::type carries typeParams, baseType, fromBaseType, and toBaseType. The two conversions are canonical fully qualified names. custom::type carries typeParams, access, and constructors.

v3 type definitions are alias::type and custom::type. v3 type specifications add opaque::type and derived::type. A custom type on a public face is public::spec::custom::type.

Spec groups

The IR stores one specification for a package and one specification for a module. The package name, and for a module the package plus the module name, are the only keys. There is no group field.

A top-level package::spec may include modules. Each entry is a module::spec and inherits that package name. Those entries combine with every top-level module::spec whose package is that package and whose name matches. A top-level module::spec may include types and values. Those entries combine with every top-level type spec and value spec that names the same package and module. A nested type or value omits package and module.

The reader walks the document from start to end. An inline list is contributed at the struct that holds it. A later top-level spec for the same name appends. An earlier top-level spec stays ahead of a later inline list. After that merge, a repeated type name or value name in one module is rejected.

Ion-to-Ion copy may keep the inline lists and the top-level specs side by side. A writer that starts from the IR emits one package::spec per package and one module::spec per module, with the merged members inline, because the IR has already combined them. def does not use this merge. One public::def::module owns the module's definitions.

package::spec::{
  name: "morphir/SDK",
  modules: [
    module::spec::{
      name: "basics",
      types: [
        public::spec::opaque::type::{ name: "int" },
      ],
    },
  ],
}

module::spec::{
  package: "morphir/SDK",
  name: "basics",
  types: [
    public::spec::opaque::type::{ name: "bool" },
  ],
}

public::spec::opaque::type::{
  package: "morphir/SDK",
  module: "basics",
  name: "float",
}

The reader builds one morphir/SDK package and one basics module. Its types are int, then bool, then float.

Dependencies

A v3 library carries its own package as definitions. The header packageName names that package. Every package::spec is a dependency, and so is every module::spec, type spec, or value spec whose package is not the header package. A package::spec whose name equals the header package is rejected. A module::spec with no package field belongs to the header package, so in v3 it is rejected too. The library's own modules are public::def::module and the other def structs.

Dependency order is the order of first mention. The first package::spec, module::spec, or member spec that names a package opens that dependency. A later fragment for the same name appends. Inside a dependency, inline modules and top-level module::spec values combine by module name, and inline types and values combine with top-level member specs, as in Spec groups.

Empty modules, types, values, and typeParams are omitted.

morphir::{
  ionVersion: "0.1.0-draft.1",
  formatVersion: "3.0.0",
  kind: library,
  packageName: "example/finance",
}

package::spec::{
  name: "morphir/SDK",
  modules: [
    module::spec::{
      name: "basics",
      types: [
        public::spec::opaque::type::{ name: "int" },
        public::spec::opaque::type::{ name: "bool" },
      ],
    },
  ],
}

module::spec::{
  package: "morphir/SDK",
  name: "basics",
  types: [
    public::spec::opaque::type::{ name: "float" },
  ],
}

module::spec::{
  package: "morphir/SDK",
  name: "list",
  types: [
    public::spec::opaque::type::{
      name: "list",
      typeParams: ["a"],
    },
  ],
}

package::spec::{
  name: "example/ratings",
  modules: [
    module::spec::{
      name: "Score",
      types: [
        public::spec::alias::type::{
          name: "Score",
          typeExp: "morphir/SDK:basics#int",
        },
      ],
    },
  ],
}

public::def::module::{
  name: "Eligibility",
  doc: "Credit eligibility.",
}

public::def::alias::type::{
  module: "Eligibility",
  name: "Decision",
  typeExp: "morphir/SDK:basics#bool",
}

morphir_footer::{}

The reader builds two dependencies, morphir/SDK then example/ratings. basics has int, bool, and float. list has one opaque type. Score has one alias. No empty arrays are written.

The same library as one record nests each dependency once. Collapse merges basics and still omits empty arrays.

morphir::{
  ionVersion: "0.1.0-draft.1",
  formatVersion: "3.0.0",
  kind: library,
  packageName: "example/finance",
  dependencies: [
    package::spec::{
      name: "morphir/SDK",
      modules: [
        module::spec::{
          name: "basics",
          types: [
            public::spec::opaque::type::{ name: "int" },
            public::spec::opaque::type::{ name: "bool" },
            public::spec::opaque::type::{ name: "float" },
          ],
        },
        module::spec::{
          name: "list",
          types: [
            public::spec::opaque::type::{
              name: "list",
              typeParams: ["a"],
            },
          ],
        },
      ],
    },
    package::spec::{
      name: "example/ratings",
      modules: [
        module::spec::{
          name: "Score",
          types: [
            public::spec::alias::type::{
              name: "Score",
              typeExp: "morphir/SDK:basics#int",
            },
          ],
        },
      ],
    },
  ],
  modules: [
    public::def::module::{
      name: "Eligibility",
      doc: "Credit eligibility.",
      types: [
        public::def::alias::type::{
          name: "Decision",
          typeExp: "morphir/SDK:basics#bool",
        },
      ],
    },
  ],
}

v3 values

A definition is public::def::value or private::def::value. It carries inputTypes, outputType, and body. A specification is public::spec::value. It carries inputs and output and has no body. An input omits its attribute payload when that payload is []. Empty inputTypes and empty inputs are omitted.

Inline values on a module combine with top-level value structs for that module, in document order, by the same rule as types.

public::def::value::{
  module: "Eligibility",
  name: "approve",
  inputTypes: [
    { name: "score", type: "morphir/SDK:basics#int" },
  ],
  outputType: "morphir/SDK:basics#bool",
  body: (lambda [score]
          (apply
            (apply (ref 'morphir/SDK:basics#equal') score)
            70)),
}

public::spec::value::{
  package: "morphir/SDK",
  module: "basics",
  name: "equal",
  inputs: [
    { name: "a", type: "morphir/SDK:basics#int" },
    { name: "b", type: "morphir/SDK:basics#int" },
  ],
  output: "morphir/SDK:basics#bool",
}

A bare Ion int is a whole number. A bare float is a float. true and false are bools. A bare symbol in expression position is a variable. () is unit. [] in pattern position is an empty list. A string, a character, a decimal, a reference, and a constructor keep a head, because a bare symbol is already a variable.

Node	Spelling
Variable	score
Reference	(ref 'morphir/SDK:basics#equal')
Constructor	(constructor 'example/finance:Eligibility#Ok')
Apply	(apply fn arg)
Lambda	(lambda [score] body)
If	(if cond then else)
Let	(let score { outputType: "morphir/SDK:basics#int", body: 70 } score)
Letrec	(letrec ((f { outputType: "...", body: (lambda [x] x) })) f)
Match	(match scrutinee [pattern body] [pattern body])
Destructure	(destructure pattern value body)
Field	(field record fieldName)
Field function	(fieldFunction fieldName)
Record	(record (fieldName value) (fieldName value))
Update	(update record (fieldName value))
Tuple	(tuple a b)
List	(list 1 2 3)
Unit	()
String	(string "hello")
Char	(char "a")
Decimal	(decimal "10.50")

(lambda [score] body) is the compact pattern. It means an as pattern over a wildcard, with empty attributes. The explicit pattern is (lambda [(as (wildcard) score)] body). A writer uses the compact parameter when that is what the IR holds.

A bare symbol in pattern position is that same compact binding. _ is a wildcard.

Node	Spelling
Wildcard	_
Binding	score or (as (wildcard) score)
As	(as pattern name)
Tuple	(tuple p1 p2)
Constructor	(constructor 'example/finance:Eligibility#Ok' p1)
Empty list	[]
Head and tail	(headTail head tail)
Literal	the same spelling as a value literal
Unit	()

When a node has a non-empty attribute payload, a struct follows the head. Writers omit that struct when the payload is [].

(apply {attributes: [{source: "generated"}]}
  (ref 'morphir/SDK:basics#not')
  score)

A let and a letrec binding carry a value definition. Empty inputTypes on that definition are omitted. The body of the binding is an expression.

Next checkpoint

IR v4 is discussion 942. The deferred nodes are below. v3 readers reject them.

Deferred to v4

specs and application distributions, entry points, structured attributes, holes, native and external and incomplete definition bodies, derived type definitions, and Morphir annotation arguments.

[DamianReeves]

Checkpoint 2. A specification may be written as several specs for one package, one module, or both. The split is an authoring group. The IR still stores one package specification and one module specification.

A spec::package or spec::module may contain a specs list as well as its direct members. Direct members come first. In the datagram, repeating spec::package with the same name, or spec::module with the same package and name, continues the same specification. An optional group string names the fragment.

Ion-to-Ion collapse keeps the fragments and their group labels. A writer that starts from the IR emits one fragment and omits group, because the IR has no group field. A repeated type or value name inside the merged module is rejected. A def module is not split this way.

The current note is the opening post of this discussion.

[DamianReeves]

Checkpoint 3. Specification annotations put the noun first: package::spec, module::spec, and opaqueType::spec. Definitions stay public::def::typeAlias.

The package name, and for a module the package plus the module name, are the only group keys. There is no group field and no anonymous spec list. Repeating package::spec or module::spec with the same name continues that specification. A repeated type or value name in the merged module is rejected. def modules do not merge.

The opening post of this discussion is the current note.

[DamianReeves]

Checkpoint 4. A top-level package::spec may include modules. Those entries combine with every top-level module::spec for that package name. A top-level module::spec may include types and values. Those entries combine with every top-level type spec and value spec for that package and module.

The reader uses document order. An inline list is contributed where its struct appears, and a later top-level spec appends. A repeated type or value name in the merged module is rejected. A writer that starts from the IR emits the merged members inline.

The opening post of this discussion is the current note.

[DamianReeves]

Checkpoint 5. A v3 dependency is a package::spec, plus any module::spec or member spec that names that package. Inline modules, types, and values combine with the matching top-level specs in document order. Dependency order is the order of first mention. The library's own package stays on the header and is written with def structs.

A writer omits an array that is allowed to be empty. A reader treats the missing array as empty. This covers dependencies, modules, types, values, typeParams, constructors, args, and arguments.

The opening post of this discussion is the current note.

[DamianReeves]

Checkpoint 6. The morphir block carries ionVersion, a SemVer 2.0 string for the Ion spelling. It is separate from IR formatVersion. The contract is new, so it starts at 0.1.0-draft.1 and a draft matches only exactly. A missing ionVersion means the latest version that reader implements, which today is 0.1.0-draft.1. Writers still emit the field. Parsing uses the semver crate.

The opening post of this discussion is the current note.

[DamianReeves]

Checkpoint 7. A member specification uses the same annotation slots as a definition. public::spec::opaqueType sits next to public::def::typeAlias. A specification is the public face, so the access is public.

package::spec and module::spec stay grouping headers. They do not take an access annotation.

The opening post of this discussion is the current note.

[DamianReeves]

Checkpoint 8. opaqueType, derivedType, and typeAlias split into a modifier and type. A specification reads public::spec::opaque::type, public::spec::derived::type, or public::spec::alias::type. A definition reads public::def::alias::type. customType is unchanged.

The opening post of this discussion is the current note.

[DamianReeves]

Checkpoint 9. customType splits the same way as the other type kinds. A definition reads public::def::custom::type. A specification reads public::spec::custom::type.

The opening post of this discussion is the current note.

[DamianReeves]

Checkpoint 10. v3 values are locked. A definition is public::def::value or private::def::value, with inputTypes, outputType, and an S-expression body. A specification is public::spec::value, with inputs and output. Apply is binary. The expression and pattern tables are in the opening post. Writers omit an attribute struct when the payload is [].

IR v4 is the next slice.

The opening post of this discussion is the current note.

[DamianReeves]

v4 continues in #942. The v3 decisions in this thread stay as they are.

[DamianReeves]

Superseded: the Ion document tree no longer uses JSON-shaped files. See #938 (comment).

Document tree. A v3 Ion document is one file. The datagram and the record in the opening post are that file. ionVersion and morphir_footer::{} belong on the datagram. The record is one morphir:: value and has no footer.

A document tree is a v4 storage profile. The CLI refuses to write v3 IR as a tree (IR v3 requires single-file storage). Migrate the library to v4, then write layout = "document-tree" and format = "ion". Each tree file is one Ion value with the members of the JSON document-tree file at the same logical path. The annotation DSL stays on the single-file distribution.

The same library as a v3 datagram. Names are canonical:

morphir::{
  ionVersion: "0.1.0-draft.1",
  formatVersion: "3.0.0",
  kind: library,
  packageName: "example/finance",
}

public::def::module::{
  name: "eligibility",
}

public::def::alias::type::{
  module: "eligibility",
  name: "decision",
  typeExp: "morphir/SDK:basics#bool",
}

morphir_footer::{}

After migration, the Ion document tree is a directory. .type is part of the logical name. .ion is the profile extension.

morphir-ir/
├── manifest.ion
└── pkg/
    └── example/
        └── finance/
            └── eligibility/
                ├── module.ion
                └── decision.type.ion

The writer emits the JSON profile's canonical text. That text is one Ion value, and a number keeps its lexeme. formatVersion in a tree file is the integer 4. The single-file header keeps the string "3.0.0" or "4.0.0".

manifest.ion:

{ "formatVersion": 4, "distribution": "Library", "package": "example/finance", "pathBudget": 4000 }

pkg/example/finance/eligibility/module.ion:

{ "formatVersion": 4, "path": "eligibility", "types": ["decision"], "values": [] }

pkg/example/finance/eligibility/decision.type.ion. Access is the key Public. This is the spelling MCK document-tree-0006 pins for a type alias:

{ "formatVersion": 4, "name": "decision", "def": { "Public": { "TypeAliasDefinition": { "typeParams": [], "typeExp": "morphir/SDK:basics#bool" } } } }

A reader also accepts the same members with symbol field names:

{
  formatVersion: 4,
  name: "decision",
  def: {
    Public: {
      TypeAliasDefinition: {
        typeParams: [],
        typeExp: "morphir/SDK:basics#bool",
      },
    },
  },
}

The v3 spelling in the opening post stays as it is. The tree rules, value files, and dependency files are in #942.

[DamianReeves]

Document tree, revised. A tree file no longer holds a JSON-shaped value. Each file holds the same annotated elements as the single-file distribution. The path is the scope. The design applies to v3 and v4. This comment covers v3. v4 trees are in #942. The work is on branch feat/amazon-ion-ir and is not merged yet.

The tree uses the same paths as the JSON and YAML trees, with the .ion extension:

manifest.ion
pkg/<package>/<module>/module.ion
pkg/<package>/<module>/<stem>.type.ion
pkg/<package>/<module>/<stem>.value.ion

Directory segments and stems are the escaped file stems. For example, morphir/SDK is morphir/_sdk.

The rules:

• The path supplies the package, the module, and the name of a node. A file may omit package, module, and name. A name that is present must match the path. The reader refuses a mismatch.
• manifest.ion holds the morphir:: header with ionVersion, formatVersion, kind, packageName, and pathBudget. For v3, formatVersion is "3.0.0".
• No tree file has a morphir_footer. The end of the file ends it.
• module.ion holds exactly one public::def::module or private::def::module. It may also hold the types and values of the module. They go after the module as top-level elements, or in the inline types and values lists of the module. A type or value in module.ion states its name, because the path does not name it.
• A type file holds exactly one type. A value file holds exactly one value.
• The reader merges the files additively, with the same rules as the single file. The module file comes first. The type files come next, then the value files. Each group is in path order. The reader refuses a type or value that the merge defines twice.
• A tree orders the modules, and the members of each module, by path. The original order is the one thing a tree does not keep.
• The writer puts only the module header in module.ion. It writes one file for each type and one file for each value. It omits every name that the path supplies.
• The path budget can cut a stem. A cut stem ends in __ plus eight hex digits and no longer spells the name. The writer keeps name in that file.
• A v3 tree has no deps/ directory. The v3 Ion codec does not encode dependencies yet.
• The reader refuses a root that has manifest.ion and another manifest, such as manifest.json or manifest.yaml. That root is ambiguous.

An example for the package example:

manifest.ion
pkg/example/eligibility/module.ion
pkg/example/eligibility/score.type.ion
pkg/example/eligibility/approve.value.ion

manifest.ion:

morphir::{
  ionVersion: "0.1.0-draft.1",
  formatVersion: "3.0.0",
  kind: library,
  packageName: "example",
  pathBudget: 4000,
}

pkg/example/eligibility/module.ion holds the module and one child. The child states its name, because the path does not name it:

public::def::module::{
  doc: "Credit eligibility.",
}

public::def::alias::type::{
  name: "decision",
  typeExp: "morphir/SDK:basics#bool",
}

pkg/example/eligibility/score.type.ion. The stem supplies score:

public::def::alias::type::{
  typeExp: "morphir/SDK:basics#int",
}

pkg/example/eligibility/approve.value.ion. The stem supplies approve:

public::def::value::{
  inputTypes: [ { name: "score", type: "morphir/SDK:basics#int" } ],
  outputType: "morphir/SDK:basics#bool",
  body: true,
}

The tree reads as this single-file datagram:

morphir::{ formatVersion: "3.0.0", kind: library, packageName: "example" }
public::def::module::{
  name: "eligibility",
  doc: "Credit eligibility.",
  types: [
    public::def::alias::type::{ name: "decision", typeExp: "morphir/SDK:basics#bool" },
    public::def::alias::type::{ name: "score", typeExp: "morphir/SDK:basics#int" },
  ],
  values: [
    public::def::value::{
      name: "approve",
      inputTypes: [ { name: "score", type: "morphir/SDK:basics#int" } ],
      outputType: "morphir/SDK:basics#bool",
      body: true,
    },
  ],
}
morphir_footer::{}

Two cases that the reader refuses.

The name does not match the path. This score.type.ion names the type rating:

public::def::alias::type::{
  name: "rating",
  typeExp: "morphir/SDK:basics#int",
}

The path names the type score, so the reader refuses the file.

The merge defines a type twice. This module.ion defines score inline, and score.type.ion also exists:

public::def::module::{
  doc: "Credit eligibility.",
  types: [
    public::def::alias::type::{ name: "score", typeExp: "morphir/SDK:basics#int" },
  ],
}

After the merge, score has two definitions, so the reader refuses the tree.

The earlier document-tree comment is superseded. The v3 spelling in the opening post stays as it is.