diff --git a/scripts/generate-schema.rb b/scripts/generate-schema.rb index 435e94e..3a2c72e 100755 --- a/scripts/generate-schema.rb +++ b/scripts/generate-schema.rb @@ -236,9 +236,9 @@ def render(groups) out << "The tag of a field is normative; it identifies the field on the " \ "wire and SHALL NOT be reused. A field marked mandatory SHALL be " \ "present. A field marked optional MAY be absent, and a " \ - "<> SHALL accept a message in which it is. A field marked " \ + "<> SHALL accept a message in which it is. A field marked " \ "repeated holds zero or more values. A field marked deprecated " \ - "SHALL NOT be written by a <>, and a consumer that reads " \ + "SHALL NOT be written by a <>, and a consumer that reads " \ "one SHALL ignore it." out << "" out << "The obligations are those in force at the IR version stated in " \ diff --git a/sources/part1/sections/03-terms-and-definitions.adoc b/sources/part1/sections/03-terms-and-definitions.adoc index f234474..2ec4c9e 100644 --- a/sources/part1/sections/03-terms-and-definitions.adoc +++ b/sources/part1/sections/03-terms-and-definitions.adoc @@ -1,12 +1,13 @@ == Terms and definitions -For the purposes of this document, the following terms and definitions apply. +// Metanorma inserts the "For the purposes of this document ..." sentence +// itself; stating it here as well printed it twice. [[model]] === model -self-contained description of a computation, comprising a top-level <>, -the <> versions it depends upon, and producer and metadata +self-contained description of a computation, comprising a top-level <>, +the <> versions it depends upon, and producer and metadata information [[graph]] @@ -18,24 +19,24 @@ outputs, initializers and value type information [[node]] === node -single invocation of an <>, binding named values to the operator's +single invocation of an <>, binding named values to the operator's formal inputs and outputs and fixing its <> [[initializer]] === initializer -named tensor value carried in a <>, being either a constant of that +named tensor value carried in a <>, being either a constant of that graph or the default value of an input of it [[subgraph]] === subgraph -<> that is the value of an <> of a <> +<> that is the value of an <> of a <> [[function]] === function -<> together with an implementation of it in terms of other operators +<> together with an implementation of it in terms of other operators Note 1 to entry: The implementation is a fallback, not a definition of the operator's numerical behaviour; see <>. @@ -43,14 +44,14 @@ operator's numerical behaviour; see <>. [[dimension-variable]] === dimension variable -name denoting an extent that is not fixed when a <> is written, and that +name denoting an extent that is not fixed when a <> is written, and that is the same wherever the name occurs in that model [[operator]] === operator named computation with a specified signature and semantics, identified by the -pair of its <> and its name +pair of its <> and its name Note 1 to entry: Operators are defined in <>. This document specifies the form such a definition takes and the rules it obeys, not the @@ -68,31 +69,31 @@ Note 1 to entry: The empty string denotes the default ONNX domain. [.alt] opset -set of operator definitions belonging to one <>, identified by that +set of operator definitions belonging to one <>, identified by that domain and a monotonically increasing integer version [[attribute]] === attribute -named value that is fixed at the time the <> is constructed and that +named value that is fixed at the time the <> is constructed and that does not participate in dataflow [[tensor]] === tensor -dense multidimensional array of elements of a single <>, having a -<> +dense multidimensional array of elements of a single <>, having a +<> [[element-type]] === element type -member of the enumeration of scalar types that the elements of a <> may +member of the enumeration of scalar types that the elements of a <> may take [[shape]] === shape -ordered sequence of dimensions of a <>, each of which is a +ordered sequence of dimensions of a <>, each of which is a non-negative integer, a symbolic name, or unknown [[conforming-implementation]] @@ -104,17 +105,17 @@ conformance classes defined in <> [[producer]] === producer -program that emits a <> +program that emits a <> [[consumer]] === consumer -program that reads a <> in order to evaluate, transform or inspect it +program that reads a <> in order to evaluate, transform or inspect it [[validation]] === validation -determination of whether a <> satisfies the requirements of this +determination of whether a <> satisfies the requirements of this document, without evaluating it [[conformance-profile]] diff --git a/sources/part1/sections/04-conformance.adoc b/sources/part1/sections/04-conformance.adoc index a2f2b32..663d3f1 100644 --- a/sources/part1/sections/04-conformance.adoc +++ b/sources/part1/sections/04-conformance.adoc @@ -21,7 +21,7 @@ not a technical one. This document defines the conformance classes listed in <>. An implementation claiming conformance to this document SHALL state which classes it claims and, for each class it claims, the -<> versions it supports. +<> versions it supports. [[tbl-conformance-classes]] .Conformance classes @@ -62,7 +62,7 @@ conformance claim. To be settled with the Steering Committee. === Operator set coverage -A <> is not required to support every operator +A <> is not required to support every operator defined in an operator set. It SHALL, however, report unambiguously which operators it does not support, and it SHALL NOT silently substitute an approximation of an unsupported operator. @@ -75,7 +75,7 @@ containing the information required by Annex A. === Relationship to Parts 2 and 3 This document specifies the form an operator definition takes and the rules an -<> obeys; it defines no operator. Operator definitions are in +<> obeys; it defines no operator. Operator definitions are in <>. A claim of conformance to this document alone is a claim about structure, diff --git a/sources/part1/sections/05-information-model.adoc b/sources/part1/sections/05-information-model.adoc index fb78641..ed3417a 100644 --- a/sources/part1/sections/05-information-model.adoc +++ b/sources/part1/sections/05-information-model.adoc @@ -3,18 +3,18 @@ === General -This clause introduces the entities of an ONNX <> and their +This clause introduces the entities of an ONNX <> and their relationships. <> states the constraints a well-formed graph satisfies; <> states what evaluating one means. === Entities and their relationships -A model contains exactly one top-level <>. +A model contains exactly one top-level <>. A graph contains an ordered sequence of <>, together with its declared inputs, outputs, initializers and value type information. -A node invokes one <>, identified by <> and name, binds named +A node invokes one <>, identified by <> and name, binds named values to that operator's formal inputs and outputs, and fixes its <>. @@ -62,7 +62,7 @@ the same graph, or an enclosing scope. | Model version | optional -| An identifier assigned by the <>, opaque to this document. +| An identifier assigned by the <>, opaque to this document. | Documentation string | optional @@ -79,11 +79,11 @@ organization responsible for the model. [[operator-set-import]] ==== Operator set imports -An <> is identified by a pair of a <> and a version. The +An <> is identified by a pair of a <> and a version. The version is a positive integer that increases monotonically as versions of that operator set are published. -A model SHALL declare, for every <> used by any node reachable from its +A model SHALL declare, for every <> used by any node reachable from its top-level graph, the operator set version of that domain that the model requires. The default domain is denoted by the empty domain name and is imported implicitly. @@ -93,7 +93,7 @@ reverse domain name based on the identity of the organization responsible for it. Every operator invoked by a node SHALL be declared by one of the operator sets -the model imports. A <> that does not implement every operator of +the model imports. A <> that does not implement every operator of every imported operator set SHALL reject the model; see <>. [[names-and-scoping]] @@ -194,7 +194,7 @@ without regard to case. === Domains as the extension point -The <> is the sole extension point of the information model. An +The <> is the sole extension point of the information model. An operator outside the domains defined by <> is a custom operator; see <>. A custom domain MAY also introduce value types of its own; see <>. diff --git a/sources/part1/sections/06-type-system.adoc b/sources/part1/sections/06-type-system.adoc index 376bc98..8d34df5 100644 --- a/sources/part1/sections/06-type-system.adoc +++ b/sources/part1/sections/06-type-system.adoc @@ -2,7 +2,7 @@ === General -Every value in an ONNX <> has a type. Types are either tensor types, +Every value in an ONNX <> has a type. Types are either tensor types, sparse tensor types, sequence types, map types, optional types or opaque types. Primitive numeric, string and Boolean types SHALL be used only as the element @@ -68,7 +68,7 @@ interchange formats, and integer element types narrower than eight bits. This subclause states their value encoding and their packing into octets. The packing is part of the wire format and is therefore normative. -Support for these types is not required of every <>; +Support for these types is not required of every <>; see <>. ==== Narrow floating-point formats @@ -218,7 +218,7 @@ A tensor type whose shape is absent denotes a tensor of unknown rank. This is distinct from a tensor of rank zero, and distinct from a tensor whose rank is known and whose extents are unknown. -The inputs and outputs of a top-level <> SHALL have a shape, so that +The inputs and outputs of a top-level <> SHALL have a shape, so that their rank is stated, even where the individual extents are not. [[dimension-variables]] @@ -227,7 +227,7 @@ their rank is stated, even where the individual extents are not. A dimension variable is a name. Two occurrences of the same dimension variable SHALL denote the same extent at evaluation. -Dimension variables are scoped to the <>, not to a graph: an occurrence +Dimension variables are scoped to the <>, not to a graph: an occurrence in a subgraph and an occurrence in an enclosing graph denote the same extent. This is what allows a model to relate an extent inside a subgraph to an extent outside it. @@ -300,7 +300,7 @@ the rule above is satisfied without appeal to the value of the variable. A type MAY carry a type denotation, and a dimension MAY carry a dimension denotation. A denotation ascribes a meaning to a type or an axis for the -benefit of a <> or a <>. +benefit of a <> or a <>. A denotation SHALL NOT affect the result of evaluating a model. A consumer MAY ignore a denotation, and MAY reject a model whose denotations are inconsistent @@ -376,7 +376,7 @@ the same mechanism as an unsupplied operator input, which is described in [[opaque-types]] ==== Opaque -An opaque type is identified by a pair of a <> and a name. The name is +An opaque type is identified by a pair of a <> and a name. The name is required; an absent or empty domain denotes the default domain. The meaning of an opaque type is defined by the operators of its domain, and diff --git a/sources/part1/sections/07-graph-structure.adoc b/sources/part1/sections/07-graph-structure.adoc index c30b86e..c8ab98f 100644 --- a/sources/part1/sections/07-graph-structure.adoc +++ b/sources/part1/sections/07-graph-structure.adoc @@ -3,7 +3,7 @@ === Graph, inputs and outputs -A <> SHALL have a name, and SHALL declare its inputs, its outputs and, +A <> SHALL have a name, and SHALL declare its inputs, its outputs and, optionally, its initializers and value type information. A top-level graph SHALL declare the name, type and shape of each of its inputs @@ -24,7 +24,7 @@ An initializer is a named tensor value carried in the graph. The order of the initializers of a graph is not significant. Where an initializer has the same name as an input of the same graph, it -specifies a default value for that input. A <> MAY allow the caller +specifies a default value for that input. A <> MAY allow the caller to supply a value for that input, overriding the initializer, and MAY allow the caller to omit it, in which case the value of the initializer is used. @@ -54,7 +54,7 @@ so under what compatibility rule; see <>. ==== General -A <> SHALL identify the <> it invokes by domain and name. +A <> SHALL identify the <> it invokes by domain and name. The number and types of a node's inputs and outputs, and the set and types of its attributes, SHALL satisfy the signature of the operator as defined in the @@ -95,7 +95,7 @@ a type, and the operators that construct and destruct it are defined in === Attributes -An <> SHALL have a name that is unique within its node. +An <> SHALL have a name that is unique within its node. An attribute value SHALL NOT refer to a value produced by dataflow: it is fixed when the graph is constructed. diff --git a/sources/part1/sections/08-graph-semantics.adoc b/sources/part1/sections/08-graph-semantics.adoc index 8d85cb7..74f1e8b 100644 --- a/sources/part1/sections/08-graph-semantics.adoc +++ b/sources/part1/sections/08-graph-semantics.adoc @@ -3,10 +3,10 @@ === Evaluation model -Evaluating a <> means computing a value for each of its declared +Evaluating a <> means computing a value for each of its declared outputs, given a value for each of its declared inputs. -A <> denotes a stateless function. Evaluating the same model on the same +A <> denotes a stateless function. Evaluating the same model on the same inputs SHALL yield the same outputs, save where an operator of the model is permitted to be non-deterministic; see <>. @@ -19,7 +19,7 @@ which the caller passes to the next invocation as an input. Evaluation is defined by the dataflow relation between nodes. This document does not prescribe an evaluation order beyond the constraint that a node's inputs are available before the node is evaluated; in particular, a -<> MAY evaluate nodes concurrently, may elide nodes +<> MAY evaluate nodes concurrently, may elide nodes whose outputs are unused, and may fuse or reassociate computations, provided that the results remain within the tolerances of <>. @@ -39,11 +39,11 @@ axis handling of `Scan`. The structural constraints are in [[functions]] === Functions -A function is an <> together with an implementation of it in terms of +A function is an <> together with an implementation of it in terms of other operators, called its function body. The body is a topologically sorted list of nodes, as a graph is. -A function is identified by a triple of a <>, a name and an overload. +A function is identified by a triple of a <>, a name and an overload. The overload distinguishes function bodies that are required to differ between call sites; where a model needs no such distinction the overload is empty. A function does not carry an operator set version of its own: the version is that @@ -57,7 +57,7 @@ value; where there is no default value, the attribute is omitted from that node. A function body is a fallback implementation, not a definition of the -operator's numerical behaviour. A <> MAY compute the +operator's numerical behaviour. A <> MAY compute the operator by any means, and the tolerances of <> apply to the operator rather than to the evaluation of its body. diff --git a/sources/part1/sections/09-inference.adoc b/sources/part1/sections/09-inference.adoc index b2529a3..3e2a8e4 100644 --- a/sources/part1/sections/09-inference.adoc +++ b/sources/part1/sections/09-inference.adoc @@ -4,10 +4,10 @@ === General Shape and type inference derives the types and shapes of values that a -<> does not state explicitly. +<> does not state explicitly. Inference is normative rather than a convenience: consumers rely on it, and a -<> is permitted to omit value type information for values other than +<> is permitted to omit value type information for values other than graph inputs and outputs. [[inference-obligations]] diff --git a/sources/part1/sections/10-validation.adoc b/sources/part1/sections/10-validation.adoc index 0074e2f..7b2b747 100644 --- a/sources/part1/sections/10-validation.adoc +++ b/sources/part1/sections/10-validation.adoc @@ -3,7 +3,7 @@ === General -Validation determines whether a <> satisfies the requirements of this +Validation determines whether a <> satisfies the requirements of this document, without evaluating it. A validating consumer SHALL perform the checks of this clause and SHALL report diff --git a/sources/part1/sections/12-serialization.adoc b/sources/part1/sections/12-serialization.adoc index 1b6573d..1194abe 100644 --- a/sources/part1/sections/12-serialization.adoc +++ b/sources/part1/sections/12-serialization.adoc @@ -3,7 +3,7 @@ === General -An ONNX <> is serialized as a Protocol Buffers message. +An ONNX <> is serialized as a Protocol Buffers message. [IMPORTANT] .Editorial note diff --git a/sources/part1/sections/14-versioning.adoc b/sources/part1/sections/14-versioning.adoc index de9d06b..eb2e79c 100644 --- a/sources/part1/sections/14-versioning.adoc +++ b/sources/part1/sections/14-versioning.adoc @@ -10,10 +10,10 @@ ONNX has three independent version axes: IR version:: the version of the structural and serialization rules given in <>, <> and <>. -Operator set version:: the version of an <>, per <>, as +Operator set version:: the version of an <>, per <>, as published in <>. -Model version:: an identifier assigned by the <>, opaque to this +Model version:: an identifier assigned by the <>, opaque to this document. [[ir-version-specified]] @@ -71,7 +71,7 @@ of <>. An operator set version SHALL NOT be changed once published. -An operator is identified by a triple of a <>, a name and the operator +An operator is identified by a triple of a <>, a name and the operator set version at which that definition of it was introduced. Where the definition of an operator changes, the changed definition is a new operator with a new such version, and the previous definition remains what it was. diff --git a/sources/part1/sections/15-security.adoc b/sources/part1/sections/15-security.adoc index 5dcc569..9c42bde 100644 --- a/sources/part1/sections/15-security.adoc +++ b/sources/part1/sections/15-security.adoc @@ -3,13 +3,13 @@ === General -A <> is data from an untrusted source unless the consumer knows +A <> is data from an untrusted source unless the consumer knows otherwise. This clause states the obligations that follow. [[threat-model]] === Threat model -A <> defends against a model crafted so that processing it causes the +A <> defends against a model crafted so that processing it causes the consumer to read or write a file the caller did not intend, to consume unbounded memory, processor time or disk, or to recur without bound. diff --git a/sources/part1/sections/16-maintenance.adoc b/sources/part1/sections/16-maintenance.adoc index 0ae5896..c0cdc58 100644 --- a/sources/part1/sections/16-maintenance.adoc +++ b/sources/part1/sections/16-maintenance.adoc @@ -3,7 +3,7 @@ === Custom domains -A model MAY use operators in a <> not defined by <>. +A model MAY use operators in a <> not defined by <>. A consumer that does not implement such a domain SHALL report the operator as unsupported under <>, and SHALL NOT evaluate the model. @@ -15,7 +15,7 @@ operator of an operator set published under <> is subject without exception to <>. An operator whose definition is not yet settled SHALL be published in a -<> of its own, and is a custom operator under the preceding subclause. +<> of its own, and is a custom operator under the preceding subclause. NOTE: Upstream reached the same position. The serialized form of an operator set carries a status of `EXPERIMENTAL` or `STABLE`, and an operator marked @@ -29,7 +29,7 @@ that supersede it. <> records the correspondence. === Adding an operator -The procedure by which an operator enters an <> is specified in +The procedure by which an operator enters an <> is specified in <>. The constraints that procedure must respect are in <>. diff --git a/sources/part1/sections/annex-b-protobuf-schema.adoc b/sources/part1/sections/annex-b-protobuf-schema.adoc index 3c46184..f9b1db6 100644 --- a/sources/part1/sections/annex-b-protobuf-schema.adoc +++ b/sources/part1/sections/annex-b-protobuf-schema.adoc @@ -11,7 +11,7 @@ This annex states the message definitions of the serialized form: 35 messages and 166 fields. -The tag of a field is normative; it identifies the field on the wire and SHALL NOT be reused. A field marked mandatory SHALL be present. A field marked optional MAY be absent, and a <> SHALL accept a message in which it is. A field marked repeated holds zero or more values. A field marked deprecated SHALL NOT be written by a <>, and a consumer that reads one SHALL ignore it. +The tag of a field is normative; it identifies the field on the wire and SHALL NOT be reused. A field marked mandatory SHALL be present. A field marked optional MAY be absent, and a <> SHALL accept a message in which it is. A field marked repeated holds zero or more values. A field marked deprecated SHALL NOT be written by a <>, and a consumer that reads one SHALL ignore it. The obligations are those in force at the IR version stated in <>. diff --git a/sources/part2/sections/03-terms-and-definitions.adoc b/sources/part2/sections/03-terms-and-definitions.adoc index ff73817..11db28f 100644 --- a/sources/part2/sections/03-terms-and-definitions.adoc +++ b/sources/part2/sections/03-terms-and-definitions.adoc @@ -1,7 +1,8 @@ == Terms and definitions -For the purposes of this document, the terms and definitions given in -<> apply. +// Metanorma opens this clause with "For the purposes of this document, the +// following terms and definitions apply." itself. +The terms and definitions given in <> apply. NOTE: In particular *operator*, *domain*, *operator set*, *attribute*, *tensor*, *element type* and *shape* are defined in Clause 3 of diff --git a/sources/part3/sections/03-terms-and-definitions.adoc b/sources/part3/sections/03-terms-and-definitions.adoc index 930d227..adea16d 100644 --- a/sources/part3/sections/03-terms-and-definitions.adoc +++ b/sources/part3/sections/03-terms-and-definitions.adoc @@ -1,12 +1,14 @@ == Terms and definitions -For the purposes of this document, the terms and definitions given in -<> apply, together with the following. +// Metanorma opens this clause with "For the purposes of this document, the +// following terms and definitions apply." itself, so this sentence adds only +// what that one does not say. +The terms and definitions given in <> also apply. [[vector-outcome]] === outcome -result of applying one <> to an implementation, being one of +result of applying one <> to an implementation, being one of _pass_, _fail_, _unsupported_ or _error_ [[test-vector-t]] diff --git a/sources/part3/sections/07-reporting.adoc b/sources/part3/sections/07-reporting.adoc index d421823..fd40dd1 100644 --- a/sources/part3/sections/07-reporting.adoc +++ b/sources/part3/sections/07-reporting.adoc @@ -12,7 +12,7 @@ A conformance report SHALL state: * the identity and version of the implementation; * the version of this package used; * the conformance class and profile claimed; -* for each vector, its identifier and its <>; +* for each vector, its identifier and its <>; * for each vector with the outcome _fail_, the achieved deviation. === Relationship to the conformance statement