NOX/Profile Syntax

The core configuration format of WS ARC services utilizing HED is XML. However since XML is somewhat complex, configuration in the simpler INI format is also possible, which in turn relies on the existence of a use-case specific profile, with the trade-off of limited configuration scope. The content of this page specifies the Profile syntax, rules and use-case examples.

PROPOSAL
This is still only a proposal, so please use the Discussion page to provide inputs and discussion. Since the text below should go into the "WS ARC service configuration manual" it should be understandable for a person with basic XML knowledge. If you are such a person and do not understand the proposal, then please indicate so, so it can be clarified.
And please do contribute to the discussion since the Profile issue really should be resolved ASAP

Mappable XML structures

A profile are able to map the following XML structures:

• [XML-1] Value of a leaf element,
• [XML-2] Value of a element attribute,
• [XML-3] Values of unbounded leaf element (XSD maxOccurs="unbounded"),
• [XML-4] Values of leaf element which is a child of a unbounded element,
• [XML-5] Values of element attribute where element is unbounded or a child of a unbounded element,
• [XML-6] Values of unbounded leaf element which is a child of a unbounded element,

Notes: For XML-4-6 the leaf element should not be restricted to be a direct child of the unbounded element.

Association of INI to XML structures

The XML structures in the above section should be mappable from INI as follows:

• [INI-XML-1] INI-tag in a section,
• [INI-XML-2] INI-tag in a section,
• [INI-XML-3.a] Identically named INI-tags contained in the same section,
• [INI-XML-3.b] Identically named INI-tags contained in multiple identically named sections with only one INI-tag in each section,
• [INI-XML-4.a] A single INI-tag in a section mapped to all leaf child elements (a default value),
• [INI-XML-4.b] Identically named INI-tags in multiple identically named sections with only a single tag in each section,
• [INI-XML-4.c] Multiple identically named INI-tags in a single section,
• [INI-XML-5.a] A single INI-tag in a section mapped to all element attributes,
• [INI-XML-5.b] Same as INI-XML-4.b,
• [INI-XML-6] Identically named INI-tags contained in multiple identically named sections each section possibly containing multiple tags.

Attributes used for mapping

Three attributes should be used for specifying how INI to XML mapping should be done (initype, inisections and initag).

• The initag attribute should specify the tag name used in the INI configuration to set the value of the mapped XML element.
• The inisections attribute should specify the INI section names, in a space separated ordered list, in which the tag specified by initag will be searched for. For some values of the initype attribute the keyword #this is allowed to be used as a section name in the inisections attribute and it has a special meaning (explained later).
• The initype attribute should specify the type of XML element being mapped (single- or multi-element or attribute) and how it should be mappable from INI. The possible values the initype attribute can take are:
  • single: Specifies that the element is a single leaf element,
  • attribute: Specifies that the element is a attribute of the parent element,
  • multi: Specifies that the element is a unbounded leaf element,
  • multielement: Specifies that the element is a unbounded element with a leaf child element which are able to reference this element,
  • multisection: Specifies that the element is a unbounded element which has one or more child elements where child elements are able reference this element.

INI-XML-MAP-1

The leaf XML element which should be configurable from INI should have the initype attribute set to single and the inisections and initag attributes should be specified as stated in the "Attributes used for mapping" section. Of the sections specified in the inisections attribute only the first section containing a tag named according to the value of the initag attribute will be mapped.

Example

• Profile

...
<foo initype="single" inisections="special common" initag="foo"/>
...

• INI

[ common ]
profile = """As Above"""
foo = foo-common-value
[ special ]
foo = foo-special-value

• Resulting XML

...
<foo>foo-special-value</foo>
...

INI-XML-MAP-2

The XML element which should have a given attribute configurable from INI should have a direct child element named according to the desired attribute name. The initype attribute of that child element should be set to attribute and the initag and inisections attributes should used as in section INI-XML-MAP-1.

Example

• Profile

...
<foo>
  <bar initype="attribute" inisections="special common" initag="bar"/>
</foo>
...

• INI

[ common ]
profile = """As Above"""
bar = bar-common-value
[ special ]
bar = bar-special-value

• Resulting XML

...
<foo bar="bar-special-value">
...

INI-XML-MAP-3.a

The unbounded leaf XML element which should be configurable from INI should have the initype attribute set to multi, the initag attribute should specify the name of the tag used to set its values and the inisections attribute specifies in order the sections in which the specified tag can appear, only the first section in which the specified tag appear will be considered.

Example

• Profile

...
<foo initype="multi" inisections="special common" initag="foo"/>
...

• INI

[ common ]
profile = """As Above"
foo = foo-common-value-1
foo = foo-common-value-2
foo = foo-common-value-3
[ special ]
foo = foo-special-value-1
foo = foo-special-value-2

• Resulting XML

...
<foo>foo-special-value-1</foo>
<foo>foo-special-value-2</foo>
...

INI-XML-MAP-3.b

The unbounded XML element which should be configurable from INI should have the initype attribute set to multisection, the initag attribute should specify the name of the tag used to set its values and the inisections attribute specifies in order the sections in which the specified tag can appear. It is only the first section in the list which also exist in INI which is considered, thus all the sections with this name will be searched for a single tag per section.

Example 1

• Profile

...
<foo initype="multisection" inisections="non-existing special common" initag="foo"/>
...

• INI

[ common ]
profile = """As Above"""
foo = foo-common-value-1
foo = foo-common-value-2
[ special ]
foo = foo-special-1-value-1
foo = foo-special-1-value-2
foo = foo-special-1-value-3
[ special ]
foo = foo-special-2-value-1
foo = foo-special-2-value-2

• Resulting XML

...
<foo>foo-special-1-value-1</foo>
<foo>foo-special-2-value-1</foo>
...

Example 2

• Profile

...
<foo initype="multisection" inisections="non-existing common" initag="foo"/>
...

• INI

[ common ]
profile = """As Above"""
foo = foo-common-1-value-1
foo = foo-common-1-value-2
[ common ]
foo = foo-common-2-value-1
foo = foo-common-2-value-2

• Resulting XML

...
<foo>foo-common-1-value-1</foo>
...

Since common sections are merged there will only be one element in this case.

INI-XML-MAP-4.a,b

The unbounded element (the parent element) should have the initype attribute set to multisection, and the inisections attribute should specify names of sections. Only the first section for which there is an existing section in INI will be considered and that section can be referred to in child elements as the #this section. The initag attribute should not be set on the parent element. The leaf child element to be mapped should have initype set to single and the initag attribute should specify the name of the tag used to set its value. The inisections attribute should specify the sections the tag can appear in. Only the first section for which the corresponding INI section contains the tag will be used. If this section is not the #this section then the value of the found tag will be mapped to the corresponding leaf child node under each of the parent elements. If any of the #this sections contains the specified tag, and no previous sections contained it, then the values of these tags are mapped to the corresponding leaf child element under each of the parent elements. If any of the #this sections do not contain the specified tag, then succeeding sections will be searched for the tag and if found its value will be mapped to the corresponding leaf child element.

Example 1

• Profile

...
<foo initype="multisection" inisections="foo">
  <bar initype="single" inisections="special common" initag="bar"/>
</foo>
...

• INI

[ common ]
profile = """As Above"""
bar = bar-common-value
[ special ]
bar = bar-special-value
[ foo ]
bar = bar-foo-1-value
[ foo ]
bar = bar-foo-2-value

• Resulting XML

...
<foo>
  <bar>bar-special-value</bar>
</foo>
<foo>
  <bar>bar-special-value</bar>
</foo>
...

INI-XML-MAP-4.c

The unbounded element (parent) should have the initype attribute set to multielement, and the inisections attribute should specify names of sections. Only the first section for which there is an existing section in INI will be considered and that section. A leaf child element can then set the initype attribute to #this making the unbounded complex XML structure mappable from a simple INI context. The parent element should have the initag attribute set to the name of the INI tag which maps that tag to the more complex XML structure. The leaf child element to be mapped should only have the initype set to #this, and the inisections and initag should 'not be set on this element.

Example

• Profile

...
<foo initype="multielement" inisections="foo" initag="bar">
  <bar initype="#this"/>
</foo>
...

• INI

[ common ]
profile = """As Above"""
bar = bar-common-value
[ special ]
bar = bar-special-value
[ foo ]
bar = bar-foo-value-1
bar = bar-foo-value-2

• Resulting XML

...
<foo>
  <bar>bar-special-value</bar>
</foo>
<foo>
  <bar>bar-special-value</bar>
</foo>
...

INI-XML-MAP-5.a,b

The unbounded element (the parent element) should have the initype attribute set to multisection, and the inisections attribute should specify names of sections. Only the first section for which there is an existing section in INI will be considered and that section can be referred to in child elements as the #this section. The initag attribute should not be set on the parent element. The child or parent element which should have an attribute mapped, should have a child element named according to the desired attribute name, and the initype attribute should be set to attribute and the initag attribute should specify the name of the tag used to set its value. The inisections attribute should specify the sections the tag can appear in. Only the first section for which the corresponding INI section contains the tag will be used. If this section is not the #this section then the value of the found tag will be mapped to the corresponding leaf child node under each of the parent elements. If any of the #this sections contains the specified tag, and no previous sections contained it, then the values of these tags are mapped to the corresponding XML attribute in the generated XML configuration. If any of the #this sections do not contain the specified tag, then succeeding sections will be searched for the tag and if found its value will be mapped to the corresponding leaf child element.

Example 1

• Profile

...
<foo initype="multisection" inisections="foo">
  <bar initype="attribute" inisections="special common" initag="bar"/>
</foo>
...

• INI

[ common ]
profile = """As Above"""
bar = bar-common-value
[ special ]
bar = bar-special-value
[ foo ]
bar = bar-foo-1-value
[ foo ]
bar = bar-foo-2-value

• Resulting XML

...
<foo bar="bar-special-value"/>
<foo bar="bar-special-value"/>
...

INI-XML-MAP-6

The unbounded element (parent) should have the initype attribute set to multisection, and the inisections attribute should specify names of sections. Only the first section for which there is an existing section in INI will be considered and that section can be referred to in child elements as the #this section. The initag attribute should not be set on the parent element.

The unbounded leaf child element which should be mappable should have the initype set to multi and the initag attribute should specify the name of the tag used to set its value.
The inisections attribute should specify the sections the tag can appear in. Only the first section for which the corresponding INI section contains the tag will be used. If this section is not the #this section, then the values of the found tags, in that section, will be mapped to the corresponding leaf child elements in generated XML configuration. If any of the #this sections contains the specified tag, and no previous sections contained it, then the values of these tags are mapped to the corresponding leaf child elements. If any of the #this sections do not contain the specified tag, then succeeding sections will be searched for the tag and if found the values of all accordingly named tags in that section, will be mapped to corresponding leaf child elements.

Example

• Profile:

...
<foo initype="multisection" inisections="multi-special-a multi-special-b">
  <bar initype="multi" inisections="#this special common" initag="bar"/>
</foo>
...

• INI:

[ common ]
profile = """As Above"""
bar = bar-common-value

[ special ]
bar = bar-special-value

[ multi-special-a ]
bar = multi-special-a-1-value-1
bar = multi-special-a-1-value-2
bar = multi-special-a-1-value-3

[ multi-special-a ]
bar = multi-special-a-2-value-1

[ multi-special-a ]
bar = multi-special-a-3-value-1
bar = multi-special-a-3-value-2
bar = multi-special-a-3-value-3
bar = multi-special-a-3-value-4

[ multi-special-b ]
bar = multi-special-b-1-value-1
bar = multi-special-b-1-value-2

[ multi-special-b ]
bar = multi-special-b-2-value-1
bar = multi-special-b-2-value-2
bar = multi-special-b-2-value-3

• Resulting XML:

<foo>
  <bar>multi-special-a-1-value-1</bar>
  <bar>multi-special-a-1-value-2</bar>
  <bar>multi-special-a-1-value-3</bar>
</foo>
<foo>
  <bar>multi-special-a-2-value-1</bar>
</foo>
<foo>
  <bar>multi-special-a-3-value-1</bar>
  <bar>multi-special-a-3-value-2</bar>
  <bar>multi-special-a-3-value-3</bar>
  <bar>multi-special-a-3-value-4</bar>
</foo>