From 9adfcf778341e6de33a8fc0dac0d81540617f0f3 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Tue, 7 Apr 2015 10:09:44 -0700 Subject: [PATCH 1/4] Add core annotations on a column for all inherited values. --- syntax/index.html | 86 ++++++++++++++++++++++++++--------------------- 1 file changed, 47 insertions(+), 39 deletions(-) diff --git a/syntax/index.html b/syntax/index.html index 9fcee582..d93663dc 100644 --- a/syntax/index.html +++ b/syntax/index.html @@ -179,17 +179,17 @@

Table groups

A group of tables comprises a set of annotated tables and a set of annotations that relate to that group of tables. The core annotations of a group of tables are:

Groups of tables MAY in addition have any number of annotations which provide information about the group of tables. Annotations on a group of tables may include:

These arise from common properties defined on table group descriptions within metadata documents, as defined in [[!tabular-metadata]]. @@ -201,23 +201,23 @@

Tables

An annotated table is a table that is annotated with additional metadata. The core annotations of a table are:

The table MAY in addition have any number of other annotations. Annotations on a table may include:

These arise from common properties defined on table descriptions within metadata documents, as defined in [[!tabular-metadata]]. @@ -229,14 +229,22 @@

Columns

A column represents a vertical arrangement of cells within a table. The core annotations of a column are:

@@ -249,11 +257,11 @@

Rows

A row represents a horizontal arrangement of cells within a table. The core annotations of a row are:

@@ -273,17 +281,17 @@

Cells

A cell represents a cell at the intersection of a row and a column within a table. The core annotations of a cell are:

There presence or absence of quotes around a value within a CSV file is a syntactic detail that is not reflected in the tabular data model. In other words, there is no distinction in the model between the second value in a,,z and the second value in a,"",z. @@ -560,7 +568,7 @@

Validating Tables

From 8c2cf085f89e6a37f0f983027a9efde221cfbca9 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Tue, 7 Apr 2015 10:17:02 -0700 Subject: [PATCH 2/4] Order annotations alphabetically. Rename column about/property/valueURL to same convention used for cells and reference the cell definition. --- syntax/index.html | 48 +++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/syntax/index.html b/syntax/index.html index d93663dc..1130861c 100644 --- a/syntax/index.html +++ b/syntax/index.html @@ -180,8 +180,8 @@

Table groups

Groups of tables MAY in addition have any number of annotations which provide information about the group of tables. Annotations on a group of tables may include: @@ -202,14 +202,14 @@

Tables

The table MAY in addition have any number of other annotations. Annotations on a table may include: @@ -229,23 +229,23 @@

Columns

A column represents a vertical arrangement of cells within a table. The core annotations of a column are:

Columns MAY in addition have any number of other annotations, such as a description. These arise from common properties defined on column descriptions within metadata documents, as defined in [[!tabular-metadata]]. @@ -257,12 +257,12 @@

Rows

A row represents a horizontal arrangement of cells within a table. The core annotations of a row are:

Rows MAY have any number of additional annotations. The annotations on a row provide additional metadata about the information held in the row, such as: @@ -281,16 +281,16 @@

Cells

A cell represents a cell at the intersection of a row and a column within a table. The core annotations of a cell are:

From 474d8490f7fedbbd856ed955d3164f94596fc4db Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Wed, 8 Apr 2015 13:57:33 -0700 Subject: [PATCH 3/4] Describe how inherited properties create column and/or cell annotations. --- metadata/index.html | 43 ++++++++++++++++++++++--------------------- syntax/index.html | 1 + 2 files changed, 23 insertions(+), 21 deletions(-) diff --git a/metadata/index.html b/metadata/index.html index 12a218a9..e2d63dcb 100644 --- a/metadata/index.html +++ b/metadata/index.html @@ -622,7 +622,7 @@

Optional Properties

@id
- If included, @id is a link property that identifies the group of tables, as defined by [[!tabular-data-model]], described by this table group description. The value of this property becomes the value of the id annotation for the table group. Publishers MAY include this to provide additional information to JSON-LD based toolchains. + If included, @id is a link property that identifies the group of tables, as defined by [[!tabular-data-model]], described by this table group description. The value of this property becomes the value of the id annotation for the group of tables. Publishers MAY include this to provide additional information to JSON-LD based toolchains.
@type
@@ -648,7 +648,7 @@

Required Properties

url

- This link property gives the single URL of the CSV file that the table is held in, relative to the location of the metadata document. The value of this property is the value of the url annotation for the table this table description describes. + This link property gives the single URL of the CSV file that the table is held in, relative to the location of the metadata document. The value of this property is the value of the url annotation for the annotated table this table description describes.

@@ -664,7 +664,7 @@

Optional Properties

notes

- An array property that provides an array of objects representing arbitrary annotations on the annotated tabular data model. The value of this property becomes the value of the notes annotation for the table. The properties on these objects are interpreted equivalently to common properties as described in . When an array of note objects B is merged into an original array of note objects A, each note object from B is appended into the array A. + An array property that provides an array of objects representing arbitrary annotations on the annotated tabular data model. The value of this property becomes the value of the notes annotation for the annotated table. The properties on these objects are interpreted equivalently to common properties as described in . When an array of note objects B is merged into an original array of note objects A, each note object from B is appended into the array A.

The Web Annotation Working Group is developing a vocabulary for expressing annotations. In future versions of this specification, we anticipate referencing that vocabulary. @@ -977,7 +977,7 @@

Columns

name

- An atomic property that gives a single canonical name for the column. The value of this property is used to create the value of the name annotation for the described column. This MUST be a string. Conversion specifications MUST use this property as the basis for the names of properties/elements/attributes in the results of conversions. + An atomic property that gives a single canonical name for the column. The value of this property is used to create the value of the name annotation for the described column. This MUST be a string. Conversion specifications MUST use this property as the basis for the names of properties/elements/attributes in the results of conversions.

For ease of reference within URI template properties, column names are restricted as defined in Variables in [[!URI-TEMPLATE]] with the additional provision that names beginning with "_" are reserved by this specification and MUST NOT be used. @@ -987,17 +987,17 @@

Columns

suppressOutput
-

A boolean atomic property. If true, suppresses any output that would be generated when converting cells in this column. The value of this property is used to create the value of the suppress output annotation for the described column.

+

A boolean atomic property. If true, suppresses any output that would be generated when converting cells in this column. The value of this property is used to create the value of the suppress output annotation for the described column.

title

- A natural language property that provides possible alternative names for the column. The value of this property is used to create the value of the titles annotation for the described column. + A natural language property that provides possible alternative names for the column. The value of this property is used to create the value of the titles annotation for the described column.

virtual
-

A boolean atomic property taking a single value which indicates whether the column is a virtual column not present in the original source. The value of this property is used to create the value of the virtual annotation for the described column. If present, a virtual column MUST appear after all other non-virtual column definitions.

+

A boolean atomic property taking a single value which indicates whether the column is a virtual column not present in the original source. The value of this property is used to create the value of the virtual annotation for the described column. If present, a virtual column MUST appear after all other non-virtual column definitions.

Virtual columns are useful for inserting cells with default values into an annotated table to control the results of conversions.

We invite comment on whether virtual columns are useful enough to include in the final recommendation in spite of the added complexity.

@@ -1088,7 +1088,7 @@

Inherited Properties

aboutUrl
-

A URI template property that MAY be used to create a unique identifier for each cell within a row when mapping data to other formats. There are no compatibility restrictions on this property. The value of this property is used to create the value of the about URL annotation for the cell.

+

A URI template property that MAY be used to create a unique identifier for each cell within a row when mapping data to other formats. There are no compatibility restrictions on this property. The value of this property is used to create the value of the about URL annotation for the described column, and the about URL annotation for the cell.

aboutUrl is typically defined on a schema description or table description. If defined on individual column descriptions, care must be taken to ensure that transformed cell values maintain a semantic relationship.

datatype
@@ -1099,54 +1099,55 @@

Inherited Properties

A value for this property is compatible with an inherited value if they are identical, or if the value is a subtype within the datatype hierarchy defined in , including if the inherited value is explicitly specified as the base of this value.

+

The value of this property is used to create the value of the datatype annotation for the described column.

We invite comment on whether datatype should allow for a "union" of types for a cell; this would allow for a set of datatypes that could be matched against the string value of a cell, choosing the first match; e.g., to match either a date or datetime.

-
required
-
-

A boolean atomic property taking a single value which indicates whether the cell must have a non-null value. The default is false. A value for this property is compatible with an inherited value only if they are identical.

-
default

- An atomic property holding a single string that is used to create a default value for the cell in cases where the original string value is an empty string. This default value MAY be used when converting the table into other formats, or when the table is displayed. If not specified, the default for the default property is the empty string, "". A value for this property is compatible with an inherited value only if they are identical. + An atomic property holding a single string that is used to create a default value for the cell in cases where the original string value is an empty string. This default value MAY be used when converting the table into other formats, or when the table is displayed. If not specified, the default for the default property is the empty string, "". A value for this property is compatible with an inherited value only if they are identical. The value of this property is used to create the value of the default annotation for the described column.

lang

- An atomic property giving a single string language code as defined by [[!BCP47]]. Indicates the language of the value within the cell. A value for this property is compatible with an inherited value if it is a sub-language of the inherited value; for example en-US is compatible with en but not fr. + An atomic property giving a single string language code as defined by [[!BCP47]]. Indicates the language of the value within the cell. A value for this property is compatible with an inherited value if it is a sub-language of the inherited value; for example en-US is compatible with en but not fr. The value of this property is used to create the value of the lang annotation for the described column.

null

- An atomic property giving the string or strings used for null values within the data. If the string value of the cell is equal to any one of these values, the cell value is null. If not specified, the default for the null property is the empty string. A value for this property is compatible with an inherited value if it is a subset of the inherited value. + An atomic property giving the string or strings used for null values within the data. If the string value of the cell is equal to any one of these values, the cell value is null. If not specified, the default for the null property is the empty string. A value for this property is compatible with an inherited value if it is a subset of the inherited value. The value of this property is used to create the value of the null annotation for the described column.

ordered
-

A boolean atomic property taking a single value which indicates whether a list that is the value of the cell is ordered (if true) or unordered (if false). The default is false. This property is irrelevant if the separator is null or undefined, but this is not an error. A value for this property is compatible with an inherited value only if they are identical.

+

A boolean atomic property taking a single value which indicates whether a list that is the value of the cell is ordered (if true) or unordered (if false). The default is false. This property is irrelevant if the separator is null or undefined, but this is not an error. A value for this property is compatible with an inherited value only if they are identical. The value of this property is used to create the value of the ordered annotation for the described column, and the ordered annotation for the described cell.

propertyUrl
-

An URI template property that MAY be used to create a URI for a property if the table is mapped to another format. There are no compatibility restrictions on this property. The value of this property is used to create the value of the property URL annotation for the cell.

+

An URI template property that MAY be used to create a URI for a property if the table is mapped to another format. There are no compatibility restrictions on this property. The value of this property is used to create the value of the property URL annotation for the described column, and the property URL annotation for the cell.

propertyUrl is typically defined on a column description. If defined on a schema description, table description or table group description, care must be taken to ensure that transformed cell values maintain an appropriate semantic relationship, for example by including the name of the column in the generated URL by using _name in the template.

+
required
+
+

A boolean atomic property taking a single value which indicates whether the cell must have a non-null value. The default is false. A value for this property is compatible with an inherited value only if they are identical. The value of this property is used to create the value of the required annotation for the described column.

+
separator

- An atomic property that MUST have a single string value that is the character used to separate items in the string value of the cell. If null or unspecified, the cell does not contain a list. Otherwise, application MUST split the string value of the cell on the specified separator character and parse each of the resulting strings separately. The cell's value will then be a list. Conversion specifications MUST use the separator to determine the conversion of a cell into the target format. See for more details. A value for this property is compatible with an inherited value only if they are identical. + An atomic property that MUST have a single string value that is the character used to separate items in the string value of the cell. If null or unspecified, the cell does not contain a list. Otherwise, application MUST split the string value of the cell on the specified separator character and parse each of the resulting strings separately. The cell's value will then be a list. Conversion specifications MUST use the separator to determine the conversion of a cell into the target format. See for more details. A value for this property is compatible with an inherited value only if they are identical. The value of this property is used to create the value of the separator annotation for the described column.

textDirection

- An atomic property that MUST have a single string value that is one of "rtl" or "ltr" (the default). Indicates whether the text within cells should be displayed by default as left-to-right or right-to-left text. The value of this property is used to create the value of the text direction annotation for the cell. A value for this property is compatible with an inherited value only if they are identical. See Bidirectional Tables in [[!tabular-data-model]] for details. + An atomic property that MUST have a single string value that is one of "rtl" or "ltr" (the default). Indicates whether the text within cells should be displayed by default as left-to-right or right-to-left text. The value of this property is used to create the value of the text direction annotation for the column, and the text direction annotation for the cell. A value for this property is compatible with an inherited value only if they are identical. See Bidirectional Tables in [[!tabular-data-model]] for details.

valueUrl
-

An URI template property that is used to map the values to the cells into URLs. See for details. There are no compatibility restrictions on this property. The value of this property is used to create the value of the value URL annotation for the cell.

+

An URI template property that is used to map the values to the cells into URLs. See for details. There are no compatibility restrictions on this property. The value of this property is used to create the value of the value URL annotation for the described column, and the value URL annotation for the cell.

This allows a cell value to define one or more RDF resources value of a cell instead of a literal values, as defined in [[rdf-concepts]]. For example, if the value were "{#reference}", each cell value of a column named reference would be used to create a URI such as http://example.com/#1234, if 1234 were a cell value of that column.

valueUrl is typically defined on a column description. If defined on a schema description, table description or table group description, care must be taken to ensure that transformed cell values maintain an appropriate semantic relationship.

@@ -1802,7 +1803,7 @@

Formats for numeric types

  • -INF.

    • - Implementations MUST add a validation error to the errors annotation for the cell if the string being parsed: + Implementations MUST add a validation error to the errors annotation for the cell if the string being parsed:

    • does not meet the numeric format defined above,
      • diff --git a/syntax/index.html b/syntax/index.html index 1130861c..a7fb7df0 100644 --- a/syntax/index.html +++ b/syntax/index.html @@ -238,6 +238,7 @@

      Columns

    • null — the string or strings which cause the value of cells having string value matching any of these values to be null, as defined in [[!tabular-metadata]].
    • number — the position of the column amongst the columns for the associated table, starting from 1.
    • property URL — the expected property URL URI template used to create a URL identifier for the property of each value of cell in this column relative to the row in which it is contained, as defined in [[!tabular-metadata]].
      • +
    • required — a boolean that indicates that values of cells in this column MUST NOT be empty.
    • separator — a string value used to create multiple values of cells in this column by splitting the string value on the separator, as defined in [[!tabular-metadata]].
    • source number — the position of the column in the file at the url of the table, or null.
    • suppress output — a boolean that indicates whether or not this column should be suppressed in any output generated from converting the table, as described in .
      • From 7d7b99a9fc914ee66d387549a259f965273cfa9c Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Wed, 8 Apr 2015 14:04:34 -0700 Subject: [PATCH 4/4] Fix cell text direction reference. --- syntax/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/syntax/index.html b/syntax/index.html index a7fb7df0..ca60d228 100644 --- a/syntax/index.html +++ b/syntax/index.html @@ -243,7 +243,7 @@

      Columns

    • source number — the position of the column in the file at the url of the table, or null.
    • suppress output — a boolean that indicates whether or not this column should be suppressed in any output generated from converting the table, as described in .
    • table — the table in which the column appears.
      • -
    • text direction — the indicator of the text direction values of cells in this column, as described in and [[!tabular-metadata]].
      • +
    • text direction — the indicator of the text direction values of cells in this column, as described in and [[!tabular-metadata]].
    • titles — any number of human-readable titles for the column, each of which has an associated language.
    • value URL — the expected value URL URI template used to create the URL identifier for the value of each cell in this, as defined in [[!tabular-metadata]].
    • virtual — a boolean that indicates whether the column is a virtual column. Virtual columns are used to extend the source data with additional empty columns to support more advanced conversions; when this annotation is false, the column is a real column, which exists in the source data for the table.