Adds notes about string name fields being empty not null

v1 version of #2

zipkin-api.yaml

@@ -209,40 +209,92 @@ definitions:
   Endpoint:
     type: object
     title: Endpoint
+    description: The network context of a node in the service graph
     properties:
       serviceName:
         type: string
-        description: 'Classifier of this endpoint in lowercase, such as "acme-frontend"'
+        required: true
+        description: |
+                    Lower-case label of this node in the service graph, such as "favstar". Set
+                    to empty string if unknown.
+                    
+                    This is a primary label for trace lookup and aggregation, so it should be
+                    intuitive and consistent. Many use a name from service discovery.
       ipv4:
         type: string
-        description: 'The text representation of a IPv4 address associated with this endpoint. Ex. 192.168.99.100'
+        format: ipv4
+        description: |
+                    The text representation of the primary IPv4 address associated with this
+                    connection. Ex. 192.168.99.100 Absent if unknown.
       ipv6:
         type: string
-        description: 'The text representation of a IPv6 address associated with this endpoint. Ex. 2001:db8::c001'
+        format: ipv6
+        description: |
+                    The text representation of the primary IPv6 address associated with a
+                    connection. Ex. 2001:db8::c001 Absent if unknown.
+                    
+                    Prefer using the ipv4 field for mapped addresses.
       port:
         type: integer
+        description: |
+                    Depending on context, this could be a listen port or the client-side of a
+                    socket. Absent if unknown. Please don't set to zero.
   Annotation:
     title: Annotation
     type: object
-    properties:
-      endpoint:
-        $ref: "#/definitions/Endpoint"
-        description: 'The host that recorded the value, primarily for query by service name.'
+    description: |
+                Associates an event that explains latency with a timestamp.
+                Unlike log statements, annotations are often codes. Ex. "sr" for ServerReceive
+    properties:     
       timestamp:
         type: integer
+        description: |
+                    Epoch **microseconds** of this event.
+                    
+                    For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC
+                    
+                    This value should be set directly by instrumentation, using the most precise
+                    value possible. For example, gettimeofday or multiplying epoch millis by 1000.
       value:
         type: string
+        description: |
+                  Usually a short tag indicating an event, like "sr"
+                  
+                  While possible to add larger data, such as garbage collection details, low
+                  cardinality event names both keep the size of spans down and also are easy
+                  to search against.
+      endpoint:
+        $ref: "#/definitions/Endpoint"
+        description: |
+                    The host that recorded this span, primarily for query by service name.
+                    
+                    Instrumentation should always record this. Usually, absent implies late
+                    data. The IP address corresponding to this is usually the site local or
+                    advertised service address. When present, the port indicates the listen
+                    port.
   BinaryAnnotation:
     title: BinaryAnnotation
     type: object
+    description: |
+                Adds context to a span, for search, viewing and analysis.
+                
+                For example, a key "your_app.version" would let you lookup traces by version.
+                A tag "sql.query" isn't searchable, but it can help in debugging when viewing
+                a trace.
     properties:
       key:
         type: string
       value:
         type: string
       endpoint:
-        $ref: '#/definitions/Endpoint'
-        description: 'The host that recorded the value, primarily for query by service name.'
+        $ref: "#/definitions/Endpoint"
+        description: |
+                    The host that recorded this span, primarily for query by service name.
+                    
+                    There is an exception, when the key is "sa", "ca" or "ma" this is an
+                    address annotation. In such case, the endpoint is not what recorded the
+                    span, rather the remote address. The value field is set to boolean true
+                    in this case. This feature was refactored in v2 format as "remoteEndpoint"
   ListOfSpans:
     title: ListOfSpans
     description: 'A list of spans with possibly different trace ids, in no particular order'
@@ -268,39 +320,81 @@ definitions:
         type: string
         maxLength: 32
         minLength: 16
-        description: 'Randomly generated, unique for a trace, set on all spans within it. 8-byte or 16-byte identifier respectively encoded as 16 or 32 lowercase hex characters.'
+        pattern: "[a-z0-9]{16,32}"
+        required: true
+        description: |
+                    Randomly generated, unique identifier for a trace, set on all spans within it.
+                    
+                    Encoded as 16 or 32 lowercase hex characters corresponding to 64 or 128 bits.
+                    For example, a 128bit trace ID looks like 4e441824ec2b6a44ffdc9bb9a6453df3
       name:
         type: string
-        description: 'Span name in lowercase (e.g. rpc method)'
+        required: true
+        description: |
+                    The logical operation this span represents in lowercase (e.g. rpc method).
+                    Set to empty string if unknown.
+                    
+                    As these are lookup labels, take care to ensure names are low cardinality.
+                    For example, do not embed variables into the name.
       parentId:
         type: string
+        pattern: "[a-z0-9]{16}"
         maxLength: 16
         minLength: 16
-        description: 'Parent span id. 8-byte identifier encoded as 16 lowercase hex characters.  Can be ommitted or set to nil if span is the root span of a trace.'
+        description: 'The parent span ID or absent if this the root span in a trace.'
       id:
         type: string
         maxLength: 16
         minLength: 16
-        description: 'Id of current span, unique in context of traceId. 8-byte identifier encoded as 16 lowercase hex characters.'
+        pattern: "[a-z0-9]{16}"
+        required: true
+        description: |
+                    Unique 64bit identifier for this operation within the trace.
+                    
+                    Encoded as 16 lowercase hex characters. For example ffdc9bb9a6453df3
       timestamp:
         type: integer
         format: int64
-        description: 'Epoch **microseconds** of the start of this span, possibly absent if this an incomplete span.'
+        description: |
+                    Epoch microseconds of the start of this span, possibly absent if
+                    incomplete.
+                    
+                    For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC
+                    
+                    This value should be set directly by instrumentation, using the most
+                    precise value possible. For example, gettimeofday or multiplying epoch
+                    millis by 1000.
+                    
+                    There are three known edge-cases where this could be reported absent.
+                     * A span was allocated but never started (ex not yet received a timestamp)
+                     * The span's start event was lost
+                     * Data about a completed span (ex tags) were sent after the fact
       duration:
         type: integer
         format: int64
-        description: 'Duration in **microseconds** of the critical path, if known. Durations of less than one are rounded up.'
+        minimum: 1
+        description: |
+                    Duration in **microseconds** of the critical path, if known. Durations of less
+                    than one are rounded up. Duration of children can be longer than their
+                    parents due to asynchronous operations.
+                    
+                    For example 150 milliseconds is 150000 microseconds.
       debug:
         type: boolean
-        description: 'Indicator whether this trace was sampled from standard traffic or forced.  Usually coupled to the X-B3-Flags header, which when set to true is a request to store this span even if it overrides sampling policy.'
+        description: |
+                    True is a request to store this span even if it overrides sampling policy.
+                    
+                    This is true when the `X-B3-Flags` header has a value of 1.
       annotations:
         title: ListOfAnnotations
         type: array
+        description: 'Associates events that explain latency with the time they happened.'
         items:
           $ref: '#/definitions/Annotation'
       binaryAnnotations:
         title: ListOfBinaryAnnotations
         type: array
+        description: 'Binary Annotations are tags that give your span context for search, viewing and analysis.'
         items:
           $ref: '#/definitions/BinaryAnnotation'
   DependencyLink: