[
https://issues.apache.org/jira/browse/AVRO-3275?focusedWorklogId=735904&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-735904
]
ASF GitHub Bot logged work on AVRO-3275:
----------------------------------------
Author: ASF GitHub Bot
Created on: 03/Mar/22 12:08
Start Date: 03/Mar/22 12:08
Worklog Time Spent: 10m
Work Description: davydog187 commented on a change in pull request #1439:
URL: https://github.com/apache/avro/pull/1439#discussion_r818593122
##########
File path: doc/src/content/xdocs/spec.xml
##########
@@ -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'.",
Review comment:
I believe it is correct as you pointed out that it's technically
metadata here. The canonical parsing form would drop it down to just the
primitive.
Can you clarify where in the spec it specifies that Record fields do not
have namespaces and thus do not have full names? Clearly they do not have a
namespace field, but that nuance was not obvious.
Thank you so much for answering this out of band! This all seems like useful
data to go back into the spec
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Issue Time Tracking
-------------------
Worklog Id: (was: 735904)
Time Spent: 1.5h (was: 1h 20m)
> Spec on naming can be better
> ----------------------------
>
> Key: AVRO-3275
> URL: https://issues.apache.org/jira/browse/AVRO-3275
> Project: Apache Avro
> Issue Type: Improvement
> Components: spec
> Affects Versions: 1.11.0, 1.10.2
> Reporter: Oscar Westra van Holthe - Kind
> Assignee: Oscar Westra van Holthe - Kind
> Priority: Trivial
> Labels: pull-request-available
> Fix For: 1.11.1
>
> Time Spent: 1.5h
> Remaining Estimate: 0h
>
> Because of a question on the mailing list, it became clear that the spec on
> naming can be improved.
> Specifically, the spec doesn't explicitly repeat in all cases on naming how
> the fullname is created.
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
