You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@avro.apache.org by rs...@apache.org on 2022/02/07 19:00:13 UTC
[avro] branch master updated: AVRO-3275: Clarify specification on naming (#1439)
This is an automated email from the ASF dual-hosted git repository.
rskraba pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/avro.git
The following commit(s) were added to refs/heads/master by this push:
new 840dec6 AVRO-3275: Clarify specification on naming (#1439)
840dec6 is described below
commit 840dec6d47b6a81e94a451c425669f025e1c88af
Author: Oscar Westra van Holthe - Kind <op...@users.noreply.github.com>
AuthorDate: Mon Feb 7 20:00:07 2022 +0100
AVRO-3275: Clarify specification on naming (#1439)
* AVRO-3275: Clarify specification on naming
* AVRO-3275: Further clarify specification on naming
Adds an example, and mentions for all occurrences of the 'namespace'
attribute that it is optional.
* AVRO-3275: Further clarify specification on naming
Minor addition
* Apply suggestions from code review
Co-authored-by: Ryan Skraba <ry...@skraba.com>
---
doc/src/content/xdocs/spec.xml | 178 ++++++++++++++++++++++++++++-------------
1 file changed, 121 insertions(+), 57 deletions(-)
diff --git a/doc/src/content/xdocs/spec.xml b/doc/src/content/xdocs/spec.xml
index 09a9d35..46aa711 100644
--- a/doc/src/content/xdocs/spec.xml
+++ b/doc/src/content/xdocs/spec.xml
@@ -90,7 +90,7 @@
<ul>
<li><code>name</code>: a JSON string providing the name
of the record (required).</li>
- <li><code>namespace</code>, a JSON string that qualifies the name;</li>
+ <li><code>namespace</code>, a JSON string that qualifies the name (optional);</li>
<li><code>doc</code>: a JSON string providing documentation to the
user of this schema (optional).</li>
<li><code>aliases:</code> a JSON array of strings, providing
@@ -165,7 +165,7 @@
<ul>
<li><code>name</code>: a JSON string providing the name
of the enum (required).</li>
- <li><em>namespace</em>, a JSON string that qualifies the name;</li>
+ <li><em>namespace</em>, a JSON string that qualifies the name (optional);</li>
<li><code>aliases:</code> a JSON array of strings, providing
alternate names for this enum (optional).</li>
<li><code>doc</code>: a JSON string providing documentation to the
@@ -257,7 +257,7 @@
the following attributes:</p>
<ul>
<li><code>name</code>: a string naming this fixed (required).</li>
- <li><code>namespace</code>, a string that qualifies the name;</li>
+ <li><code>namespace</code>, a string that qualifies the name (optional);</li>
<li><code>aliases:</code> a JSON array of strings, providing
alternate names for this enum (optional).</li>
<li><code>doc</code>: a JSON string providing documentation to the
@@ -273,60 +273,125 @@
</section> <!-- end complex types -->
<section id="names">
- <title>Names</title>
- <p>Record, enums and fixed are named types. Each has
+ <title>Names</title>
+ <p>Record, enums and fixed are named types. Each has
a <em>fullname</em> that is composed of two parts;
- a <em>name</em> and a <em>namespace</em>. Equality of names
- is defined on the fullname.</p>
- <p>The name portion of a fullname, record field names, and
- enum symbols must:</p>
- <ul>
- <li>start with <code>[A-Za-z_]</code></li>
- <li>subsequently contain only <code>[A-Za-z0-9_]</code></li>
- </ul>
+ a <em>name</em> and a <em>namespace</em>. Equality of names
+ is defined on the fullname.
+ </p>
+ <p>The name portion of a fullname, record field names, and
+ enum symbols must:
+ </p>
+ <ul>
+ <li>start with
+ <code>[A-Za-z_]</code>
+ </li>
+ <li>subsequently contain only
+ <code>[A-Za-z0-9_]</code>
+ </li>
+ </ul>
<p>A namespace is a dot-separated sequence of such names.
- The empty string may also be used as a namespace to indicate the
- null namespace.
- Equality of names (including field names and enum symbols)
- as well as fullnames is case-sensitive.</p>
- <p> The null namespace may not be used in a dot-separated
- sequence of names. So the grammar for a namespace
- is:</p>
- <p> <code><empty> | <name>[(<dot><name>)*]</code></p>
+ The empty string may also be used as a namespace to indicate the
+ null namespace.
+ Equality of names (including field names and enum symbols)
+ as well as fullnames is case-sensitive.
+ </p>
+ <p>The null namespace may not be used in a dot-separated
+ sequence of names. So the grammar for a namespace
+ is:
+ </p>
+ <p> <code><empty> | <name>[(<dot><name>)*]</code>
+ </p>
+
<p>In record, enum and fixed definitions, the fullname is
- determined in one of the following ways:</p>
- <ul>
- <li>A name and namespace are both specified. For example,
- one might use <code>"name": "X", "namespace":
- "org.foo"</code> to indicate the
- fullname <code>org.foo.X</code>.</li>
- <li>A fullname is specified. If the name specified contains
- a dot, then it is assumed to be a fullname, and any
- namespace also specified is ignored. For example,
- use <code>"name": "org.foo.X"</code> to indicate the
- fullname <code>org.foo.X</code>.</li>
- <li>A name only is specified, i.e., a name that contains no
- dots. In this case the namespace is taken from the most
- tightly enclosing schema or protocol. For example,
- if <code>"name": "X"</code> is specified, and this occurs
- within a field of the record definition
- of <code>org.foo.Y</code>, then the fullname
- is <code>org.foo.X</code>. If there is no enclosing
- namespace then the null namespace is used.</li>
- </ul>
- <p>References to previously defined names are as in the latter
- two cases above: if they contain a dot they are a fullname, if
- they do not contain a dot, the namespace is the namespace of
- the enclosing definition.</p>
- <p>Primitive type names have no namespace and their names may
- not be defined in any namespace.</p>
- <p> A schema or protocol may not contain multiple definitions
- of a fullname. Further, a name must be defined before it is
- used ("before" in the depth-first, left-to-right traversal of
- the JSON parse tree, where the <code>types</code> attribute of
- a protocol is always deemed to come "before" the
- <code>messages</code> attribute.)
- </p>
+ determined according to the algorithm below the example:
+ </p>
+ <source>
+{
+ "type": "record",
+ "name": "Example",
+ "doc": "A simple name (attribute) and no namespace attribute: use the null namespace (\"\"); the fullname is 'Example'.",
+ "fields": [
+ {
+ "name": "inheritNull",
+ "type": {
+ "type": "enum",
+ "name": "Simple",
+ "doc": "A simple name (attribute) and no namespace attribute: inherit the null namespace of the enclosing type 'Example'. The fullname is 'Simple'.",
+ "symbols": ["a", "b"]
+ }
+ }, {
+ "name": "explicitNamespace",
+ "type": {
+ "type": "fixed",
+ "name": "Simple",
+ "namespace": "explicit",
+ "doc": "A simple name (attribute) and a namespace (attribute); the fullname is 'explicit.Simple' (this is a different type than of the 'inheritNull' field).",
+ "size": 12
+ }
+ }, {
+ "name": "fullName",
+ "type": {
+ "type": "record",
+ "name": "a.full.Name",
+ "namespace": "ignored",
+ "doc": "A name attribute with a fullname, so the namespace attribute is ignored. The fullname is 'a.full.Name', and the namespace is 'a.full'.",
+ "fields": [
+ {
+ "name": "inheritNamespace",
+ "type": {
+ "type": "enum",
+ "name": "Understanding",
+ "doc": "A simple name (attribute) and no namespace attribute: inherit the namespace of the enclosing type 'a.full.Name'. The fullname is 'a.full.Understanding'.",
+ "symbols": ["d", "e"]
+ }
+ }
+ ]
+ }
+ }
+ ]
+}
+ </source>
+ <p>The fullname of a record, enum or fixed definition is determined by
+ the required `name` and optional `namespace` attributes like this:</p>
+ <ul>
+ <li>A fullname is specified. If the name specified contains
+ a dot, then it is assumed to be a fullname, and <em>any
+ namespace also specified is ignored</em>. For example,
+ use <code>"name": "org.foo.X"</code> to indicate the
+ fullname <code>org.foo.X</code>.
+ </li>
+ <li>A simple name (a name that contains no dots) and namespace are
+ both specified. For example, one might use
+ <code>"name": "X", "namespace": "org.foo"</code> to indicate the
+ fullname <code>org.foo.X</code>.
+ </li>
+ <li>A simple name only is specified (a name that contains no dots).
+ In this case the namespace is taken from the most tightly enclosing
+ named schema or protocol, and the fullname is constructed from that
+ namespace and the name. For example, if <code>"name": "X"</code> is
+ specified, and this occurs within a field of the record definition
+ of <code>org.foo.Y</code>, then the fullname is <code>org.foo.X</code>.
+ This also happens if there is no enclosing namespace (i.e., the
+ enclosing schema definition has the null namespace).
+ </li>
+ </ul>
+ <p>References to previously defined names are as in the latter
+ two cases above: if they contain a dot they are a fullname, if
+ they do not contain a dot, the namespace is the namespace of
+ the enclosing definition.
+ </p>
+ <p>Primitive type names have no namespace and their names may
+ not be defined in any namespace.
+ </p>
+ <p>A schema or protocol may not contain multiple definitions
+ of a fullname. Further, a name must be defined before it is
+ used ("before" in the depth-first, left-to-right traversal of
+ the JSON parse tree, where the <code>types</code> attribute of
+ a protocol is always deemed to come "before" the
+ <code>messages</code>
+ attribute.)
+ </p>
</section>
<section>
@@ -833,9 +898,8 @@
<p>A protocol is a JSON object with the following attributes:</p>
<ul>
- <li><em>protocol</em>, a string, the name of the protocol
- (required);</li>
- <li><em>namespace</em>, an optional string that qualifies the name;</li>
+ <li><em>protocol</em>, a string, the name of the protocol (required);</li>
+ <li><em>namespace</em>, an optional string that qualifies the name (optional);</li>
<li><em>doc</em>, an optional string describing this protocol;</li>
<li><em>types</em>, an optional list of definitions of named types
(records, enums, fixed and errors). An error definition is