Values of Structure DataTypes are sequences of name-value pairs. In many cases the value will be an array or another Structure. There are situations where it is necessary to refer to an element within a Structure. The Structure FieldPath defines a path to a single value within a Structure.
The description for a Structure FieldPath is found in Table 9.
Table 9 – Description for a Structure FieldPath
|
<path> |
= <path-element> *("." <path-element>) |
|
<path-element> |
= <name> / <index> |
|
<name> |
= 1*<char> / "'" 1*<char> "'" |
|
<index> |
= "[" 1*DIGIT *("," 1*DIGIT) "]" |
|
<char> |
= UNICODE-NO-CONTROL-OR-ESCAPED / <escaped> |
|
<escaped> |
= ".." / "[[" |
The UNICODE-NO-CONTROL-OR-ESCAPED is a core rule that includes all UNICODE characters except for U+0027 (') and any character with a category of Cc (control codes).
Any apostrophe (U+0027 (')) in a <name> is escaped by adding an extra copy of the same character and the name shall be enclosed with apostrophes.
Any <name> may be enclosed with apostrophes. Any <name> that contains U+0027 ('), U+005B ([), U+005B (]), or U+002E (.) shall be enclosed with apostrophes.
The <name> comes from the Name of a field in the DataTypeDefinition for the Structure.
The <index> is an index in field containing an array value. If an array has multiple dimensions, then the <index> has multiple elements separated by U+002C (,).
The DataTypeDefinition for a simple Structure is found in Table 10.
Table 10 – DataTypeDefinition for a simple Structure
|
Field Name |
DataType |
Description |
|
Red |
Boolean |
Simple Boolean value. |
|
Yellow.One |
Int32 |
Int32 value with a special character in the name. |
|
Green's |
String [] |
Array of string values. |
The value for the simple Structure using JSON:
{
"Red": true,
"Yellow.One": 42,
"Green's": [ "macintosh", "fuji", "ambrosia" ]
}
Examples of FieldPaths and their values based on the simple Structure value are in Table 11.
Table 11 – Examples of FieldPaths for a Simple Structure
|
FieldPath |
Resolved Value |
|
'Yellow.One' |
42 |
|
'Green''s' |
["macintosh", "fuji", "ambrosia"] |
|
'Green''s'.[1] |
"fuji" |
|
Pink |
Cannot be resolved because name not found. |
|
'Green''s'.[6] |
Cannot be resolved because of index too large. |
|
'Green''s'.[TEXT] |
Cannot be resolved because of non-numeric index. |
The DataTypeDefinition for a complex Structure is found in Table 12.
Table 12 – DataTypeDefinition for a Complex Structure
|
Field Name |
DataType |
Description |
|
Apple |
SimpleStructure [] |
An array of the Structure defined in Table 10. |
|
[Banana] |
Structure |
Any Structure value. |
|
Grape |
BaseDataType |
Any value. |
The value for the complex Structure using JSON:
{
"Apple": [
{
"Red": true,
"Yellow.One": 42,
"Green's": [ "macintosh", "fuji", "ambrosia" ]
}
],
"[Banana]": {
"TypeId": "<type-id>",
"Body": {
"X": 987,
"Y": 432
},
"Grape": {
"Type": 6
"Body": [ 123, 345, 678 ]
},
}
Examples of FieldPaths and their values based on the complex Structure value are in Table 13.
Table 13 – Examples of FieldPaths in a Complex Structure
|
FieldPath |
Resolved Value |
|
Apple.[0] |
{ "Red": true, "Yellow.One": 42, "Green": [ "macintosh", "fuji", "ambrosia" ] } |
|
Apple.[0].'Yellow.One' |
42 |
|
Apple.[0].'Green''s' |
["macintosh", "fuji", "ambrosia"] |
|
Apple.[0].'Green''s'.[1] |
"fuji" |
|
'[Banana]' |
{ "TypeId": "<type-id>", "Body": { "X": 987, "Y": 432 } } |
|
'[Banana]'.Body |
{ "X": 987, "Y": 432 } |
|
'[Banana]'.Body.Y |
432 |
|
Grape |
{ "Type": 6 "Body": [ 123, 345, 678 ] } |
|
Grape.Body.[1] |
345 |