[
https://issues.apache.org/jira/browse/AVRO-3275?focusedWorklogId=737643&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-737643
]
ASF GitHub Bot logged work on AVRO-3275:
----------------------------------------
Author: ASF GitHub Bot
Created on: 07/Mar/22 17:15
Start Date: 07/Mar/22 17:15
Worklog Time Spent: 10m
Work Description: RyanSkraba commented on a change in pull request #1439:
URL: https://github.com/apache/avro/pull/1439#discussion_r820922683
##########
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:
> Can you clarify where in the spec it specifies that Record fields do
not have namespaces and thus do not have full names?
I agree that it's not great, and specified "by omission"
[here](https://github.com/apache/avro/blob/release-1.11.0/doc/src/content/xdocs/spec.xml#L277-L282)
To paraphrase: `Record, enum and fixed each have a fullname composed of
namespace and name... The name portion of a fullname, record field names, and
enum symbols must match [an alphanumeric regex without dot]` I raised
AVRO-3436 because it would be simple to clarify!
--
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: 737643)
Time Spent: 2h 10m (was: 2h)
> 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: 2h 10m
> 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)
