0029 - A link to a table is one qualifier facet holding the uri of the table
Status: accepted
Context
Two things need to point at a table the standard gives no field to point at:
- a column of a table that holds the key of another table, or the rank of one of its rows;
- a property whose components have axes (a length from -40 to 40 m, sixteen angles) that live in a table.
RESQML TRG 2.2 section 7.1 (p. 222) gives a property labels per component and nothing else; EML TRG 2.3 has no link from a column to a table. Left to each reader, the link would be read as many ways as there are readers, and each way is a guess about what a producer meant.
What the standard does say, and what a link can rest on:
- EML TRG 2.3 section 11.11
PropertyKindFacet(p. 294): “Don’t use several facets of the same kind for the same property.” Onequalifierfacet can carry one link; a second beside it cannot be a second link. - EML TRG 2.3 section 11.3
FacetKind(p. 285):qualifieris “used to capture any other context not covered by the other facet types listed here”. An ordinary qualifier (cumulative,measured) is context, not a link. - EML TRG 2.3 section 11.2
FacetExt(p. 284): the list of values is open, so a uri is a legal value.
Decision
- Convention B. A column, or a property, links to a table by one facet of
kind
qualifierwhose value is the full ETP uri of that table. The convention is this library’s own, written down here. - One reading.
property::qualifier_link(facets)is the only function that reads it. It returns the uri,Ok(None)when noqualifierfacet holds a uri (an ordinary qualifier is left alone), and refuses by name: a uri beside anotherqualifierfacet isSeveral { count }(the standard allows one facet of a kind), a value that starts like an ETP uri and is not the uri of an object (a dataspace uri, a truncated one) isMalformedUri. It does not say whether the object named is a table: each caller checks that against what it needs. The table side (column links,LinkReaders) and the property side (axes) both call it; neither reads a facet list a second way. - The axes of a property. The table the facet names holds exactly one key
column, and one value column per dimension of the components, in the order
of the document, the slowest dimension first. That order is an
interpretation: the standard states none for a table. A table has one row count
for all its columns, so a shape whose dimensions differ (
[3, 2]) does not fit a table and is refused by name. A table with another number of value columns, or of key columns, is refused by name. - A declared source comes before the file. What the caller declares (a table,
a paired property, a WITSML channel) is tried before what the file says
(convention B,
LabelPerComponent); the first source to answer for a dimension wins, and a dimension nobody answers for has its ranks and says so. A source that applies and fails refuses: an axis that was declared is never silently replaced by ranks. A table that merely looks right is offered (candidate_tables) and never applied. - Nothing is written to the package by this reading: a declaration the caller makes is a parameter, kept in a recipe or a view document.
UseIntervalis read asn - 1steps forninstants. The standard names the field without a text (EML TRG 2.3, p. 296,TimeOrIntervalSeries); the library has read a value per interval since before this decision (TimeRef), and the shape of a property keeps that reading.
Consequences
- A column or a property that links by convention A (the target written in a description) is not read by this function; the table side reads it, with a warning (see the decision on table links).
- A producer that writes two
qualifierfacets, one of them a uri, gets a named refusal rather than a silent choice of the first. - The order of the value columns is the one place a file written by someone else may mean the opposite; the refusal of unequal dimensions catches the case where it matters most, and a reordering is the caller’s declaration.