Field metadata
What is a field
The eForms Regulation defines, in table 2 of its annex, a set of business terms (BT) for the various pieces of information that are in a notice.
But the level of granularity of those BTs is not sufficient to accurately reflect the structure of the information in the XML notices.
For example, there is a single business term, BT-27, for the estimated value of the procurement procedure or lot. But the estimated value of a lot is in a different location in the XML, and will be subject to different rules, than the estimated value of the whole procedure.
The notion of fields was added to resolve those ambiguities. Each field is related to one single business term in a particular context, and corresponds to a more precise definition of the information it contains. The identifier of a field always starts with the identifier of the corresponding business term.
For the example above, the fields defined for BT-27 are:
-
BT-27-Procedure : estimated value of the procedure
-
BT-27-Lot : estimated value of a lot
-
BT-27-Part : estimated value of a part
-
BT-27-LotsGroup : estimated value of a group of lots
The field repository
The structure and content of the field repository described below are driven by the specific needs of our various applications. As we think it could be useful for others, we are sharing it publicly, and you are free to make use of it. However we currently do not guarantee the stability of the structure or content described here. |
The field repository is a JSON file that contains all relevant information for each field we have defined, in a structured and reusable form.
We are using this file to provide the definition of all fields to our form-filling application (eNotices2). Each form is then made of a specific subset of those fields.
The field repository is mainly an array of fields, preceded by some version information and the general structure of XML notices:
{
"ublVersion": "2.3", (1)
"sdkVersion" : "eforms-sdk-0.5.0", (2)
"metadataDatabase": { (3)
"version": "0.2.53",
"createdOn": "2021-11-20T16:46:39"
},
"xmlStructure" : [ (4)
{ ... },
...
],
"fields": [ (5)
{ ... },
...
]
}
1 | Version of the UBL standard used. |
2 | Version of the eForms SDK the file belongs to. |
3 | Version number and date of the data used to create this file. |
4 | General structure of XML notices. See the XML Structure page. |
5 | List of fields. |
Field properties
The various characteristics of each field are indicated as properties of the JSON object that represents it.
{
{
"id" : "BT-01-notice", (1)
"parentNodeId" : "ND-0", (2)
"name" : "Procedure Legal Basis", (3)
"btId" : "BT-01", (4)
"xpathAbsolute" : "/*/cbc:RegulatoryDomain", (5)
"xpathRelative" : "cbc:RegulatoryDomain", (6)
"type" : "code", (7)
"legalType" : "CODE", (8)
"maxLength" : 400, (9)
"repeatable" : { (10)
"value" : false
},
"codeList" : { (11)
"value" : {
"id" : "legal-basis",
"type" : "flat"
}
}
}, {
"id" : "BT-137-Lot",
"parentNodeId" : "ND-Lot",
"name" : "Purpose Lot Identifier",
"btId" : "BT-137",
"xpathAbsolute" : "/*/cac:ProcurementProjectLot[cbc:ID/@schemeName='Lot']/cbc:ID",
"xpathRelative" : "cbc:ID",
"type" : "id",
"idScheme" : "LOT", (12)
"legalType" : "IDENTIFIER",
"repeatable" : {
"value" : false,
"severity" : "ERROR"
},
"forbidden" : { (13)
"value" : false,
"severity" : "ERROR",
"constraints" : [ {
"noticeTypes" : [ "1", "2", "3", "4", "5", "6", "X01", "X02" ],
"value" : true,
"severity" : "ERROR"
} ]
},
"mandatory" : { (14)
"value" : false,
"severity" : "ERROR",
"constraints" : [ {
"noticeTypes" : [ "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "CEI", "T01", "T02" ],
"value" : true,
"severity" : "ERROR"
} ]
},
"pattern" : { (15)
"value" : "^LOT-\\d{4}$",
"severity" : "ERROR"
}
}, {
"id" : "BT-13714-Tender",
"parentNodeId" : "ND-LotTender",
"name" : "Tender Lot Identifier",
"btId" : "BT-13714",
"xpathAbsolute" : "/*/ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/efext:EformsExtension/efac:NoticeResult/efac:LotTender/efac:TenderLot/cbc:ID",
"xpathRelative" : "efac:TenderLot/cbc:ID",
"type" : "id-ref",
"idSchemes" : [ "LOT", "GLO" ], (16)
"legalType" : "IDENTIFIER",
"repeatable" : {
"value" : false,
"severity" : "ERROR"
},
"forbidden" : {
...
},
"mandatory" : {
...
},
"pattern" : {
...
}
}
...
}
1 | Identifier of the field. |
2 | Identifier of the node (XML element) that contains the field. |
3 | Short name of the field. |
4 | Identifier of the business term to which the field corresponds. |
5 | Location of the field in an XML notice, as an absolute XPath. |
6 | Location of the field in an XML notice, relative to its parent node. |
7 | Technical data type of the field. |
8 | Data type of the business term, as indicated in the eForms Regulation. |
9 | Maximum number of characters allowed in the value of the field, optional. |
10 | Indicates if the field can appear more than once inside its container |
11 | Identifier of the code list from which the field value must belong. Applicable only for fields of type "code" or "internal-code" |
12 | Identifier scheme used by a field with "type" : "id" . |
13 | This property provides information on when a field’s presence is forbidden. |
14 | This property provides information on when a field’s value is mandatory. |
15 | A RegEx pattern the field’s value must match. |
16 | Array indicating the valid idScheme values which this identifier reference field ("type" : "id-ref" ) can reference. |
Property Values
Some properties are assigned with a static value; a value that does not depend on any conditions and does not change. For example the "btId" property (indicating the business term associated with the field) is assigned a static value because it is always the same.
The properties that are assigned with static values are listed below:
Static Properties
id
|
A string specifying the identifier of a field. |
parentNodeId
|
The identifier of the the parent node of the field. All nodes are listed in the |
name
|
The name of the field. It is provided to improve readability of the |
btId
|
The identifier of the Business Term that this field instantiates. |
xpathAbsolute
|
The absolute XPath of the field. This value is calculated by combining all the relative XPaths in the hierarchy of nodes that include this field. See |
xpathRelative
|
The XPath of the field relative to its parent |
type
|
The data type of the field. See Field data types. |
presetValue
|
The value used to pre-fill a field. This property is always a string, but the value should be converted to the same type as the field. The value "{NOW}" corresponds to the current date or time. |
legalType
|
The data type of the Business Term associated with the field as defined by the eForms Regulation. |
maxLength
|
The maximum number of characters that the field can hold. |
idScheme
|
Applicable only to fields of type |
schemeName
|
Applicable only to fields of type |
idSchemes
|
Applicable only to fields of type |
Static properties are always assigned with a scalar value (a string, a boolean, a number, array of strings, etc.). If there is no value defined, the property is omitted.
Withheld publication mechanism
The information in some fields can be withheld from publication for a defined period. For those fields, the information necessary for this mechanism is grouped under a privacy
property, which contains static properties.
{
"id" : "BT-161-NoticeResult",
...
"privacy" : {
"code" : "not-val", (1)
"unpublishedFieldId" : "BT-195(BT-161)-NoticeResult", (2)
"reasonCodeFieldId" : "BT-197(BT-161)-NoticeResult", (3)
"reasonDescriptionFieldId" : "BT-196(BT-161)-NoticeResult", (4)
"publicationDateFieldId" : "BT-198(BT-161)-NoticeResult" (5)
},
...
}
1 | Code value to use to designate this field as withheld. |
2 | Id of the field to use to indicate the code above. |
3 | Id of the field to use for the justification code. |
4 | Id of the field to use for the justification description. |
5 | Id of the field to use for the publication date. |
Dynamic properties
Every other property, apart from the ones listed above, is assigned a dynamic value. This is because the value of the property may depend on different factors, for example the notice type it is used in, or the values of other fields in the same notice.
Dynamic values are represented with a JSON object. The object always contains a value
property which indicates the default value for the dynamic property and, when necessary, a constraints
list that indicates the conditions under which the dynamic property may take different values.
repeatable
-
The
repeatable
property indicates whether or not a field can appear more than once inside its container. The current version of the eForms SDK does not contain any fields that are only repeatable under certain conditions. However therepeatable
property is a dynamic property so that constraints can be added to this property if needed in the future."repeatable" : { "value" : false, "severity" : "ERROR" }
forbidden
-
The
forbidden
property indicates whether or not the field can be used in specific notice types."forbidden" : { "value" : false, (1) "severity" : "ERROR", (2) "constraints" : [ { "noticeTypes" : [ "38", "39", "40", "X01", "X02" ], "value" : true, "severity" : "ERROR" (2) } ] }
1 Every field is allowed by default in all notice types unless a constraint forbids it. 2 The severity can be either "ERROR" or "WARN" and is provided for use by validation systems. mandatory
-
The
mandatory
property indicates whether or not a field is required to have a value."mandatory" : { "value" : false, (1) "severity" : "ERROR", (2) "constraints" : [ { "noticeTypes" : [ "1", "4", "7", "10", "14", "16", "19", "23", "29", "32", "35", "36", "CEI", "T01", "T02" ], "value" : true, "severity" : "ERROR" (2) } ] }
1 Every field is optional by default in all notice types unless a constraint specifies otherwise. 2 The severity can be either "ERROR" or "WARN" and is provided for use by validation systems. The UBL specification does not permit XML documents to contain empty elements or attributes. So if a field is not mandatory and no value has been filled in, then the corresponding XML element must be omitted from the XML notice. The value of the forbidden
property must take precedence over the value themandatory
property. If a field is forbidden, then it should not be present in the notice regardless of the value of itsmandatory
property. You should always check first if a field is forbidden or not. Then, consider whether the field is mandatory or optional only if the field is not forbidden. codelist
-
The
codeList
property indicates that the field only accepts a specific set of values, and these values are codes from a specific codelist defined for eForms.The value is a JSON object that contains the identifier of the codelist, and some information about this codelist.
"codeList" : { "value" : { "id" : "accelerated-procedure", "type" : "flat", (1) "parentId" : "indicator" (2) }, "severity" : "ERROR" }
1 Indicates that the codelist is a simple list of values. The few codelists that have a structure, like NUTS and CPV, are indicated as "hierarchical". 2 Indicates the parent codelist. Provided only for tailored codelists.
When generating the notice XML, set the @listName XML attribute to the value indicated by parentId . If parentId is not provided then use the value indicated by id as the value of the @listName XML attribute.
|
pattern
-
The
pattern
property indicates that the value of the field must match a specific regular expression pattern."pattern" : { "value" : "^LOT-\\d{4}$", (1) "severity" : "ERROR" }
1 The value of this field must be "LOT-" followed by 4 digits. In the regular expression, the backslash character "\" is escaped as "\\".
assert
-
The
assert
property gives an assertion, as a boolean EFX expression, that is expected to evaluate to "true". This is used to specify rules on the field value, and those rules can depend on other fields."assert" : { "value" : "{ND-Root} ${TRUE}", (1) "severity" : "ERROR", "constraints" : [ { "condition" : "{ND-LotResult} ${OPT-320-LotResult is present}", (2) "value" : "{ND-LotResult} ${every text:$tender in OPT-320-LotResult satisfies ($tender == OPT-321-Tender)}", (3) "severity" : "ERROR", "message" : "rule|text|BR-OPT-00320-0100" (4) } ] }
1 The default expression for the assertion is always true. 2 Condition that needs to be "true" for the constraint to be applicable. 3 The expression of the assertion, must evaluate to "true" for the constraint to be respected. 4 The identifier of message corresponding to the assertion. The message is available in the translations folder. inChangeNotice
-
The
inChangeNotice
property indicates whether the values of the field can be modified in a change notice, compared to the notice being changed (the original notice). Constraints can be added to this property when needed, to indicate that the field value can be modified in a change notice except under specific conditions."inChangeNotice" : { "value" : { "canAdd" : false, (1) "canModify" : false, (2) "canRemove" : false (3) }, "severity" : "ERROR" }
1 When false, all values in the change notice must also be in the original notice. Relevant only for repeatable fields. 2 When false, the value in the change notice must be equal to the value in the original notice. 3 When false, all values in the original notice must also be in the change notice. Relevant only for repeatable fields. By default, a field can be modified in a change notice, the default values for
canAdd
,canModify
andcanRemove
istrue
.
In the following snippet, a dynamic value is assigned to the forbidden
dynamic property:
"forbidden" : {
"value" : false, (1)
"constraints" : [ { (2)
"noticeTypes" : [ "22", "38", "39", "40", "X01", "X02" ], (3)
"value" : true, (4)
"severity" : "ERROR"
}, {
"noticeTypes" : [ "2", "5", "8", "11", "14", "15", "17", "19", "24", "30", "32", "35", "37" ],
"condition" : "{ND-AcceleratedProcedureJustification} ${BT-105-Procedure in ('open','restricted')}", (5)
"value" : true, (4)
"severity" : "ERROR"
} ]
},
1 | The default value of the property will be false in this example |
2 | List of constraints for this property. |
3 | The first constraint in this example specifies a different value than the default one in the case that the field is used in one of the notice types indicated. |
4 | The value of this dynamic property in the case that the constraint applies is indicated here. |
5 | The second constraint in this example, does not only require specific notice types but also indicates a specific condition that needs to be true for the constraint to be applicable. |
All dynamic values are always represented in the same way as in the example above. The structure of this object is illustrated in the abstract snippet below:
"propertyName" : {
"value" : "scalar1", (1)
"severity" : "ERROR", (6)
"constraints" : [ (2)
{
"noticeTypes" : [ "noticeType1", "noticeType2" ], (3)
"condition": "Boolean expression in EFX", (4)
"value" : "scalar2", (5)
"severity" : "ERROR" (6)
},
... (7)
]
}
1 | Use this default value for the property if none of the provided constraints applies. This value is always provided. |
2 | A list of constraints will be provided if needed. If not, use the default value provided. |
3 | This constraint only applies for these notice types. Every constraint specifies the notice types for which it applies. |
4 | This condition must evaluate to true for the constraint to be applicable. A condition is provided only when one is needed. |
5 | This is the value that the property should take if the constraint is applicable. |
6 | The severity is provided for validation systems. It may be either "ERROR" or "WARN". "WARN" indicates that a notice that does not comply with the provided value is still considered valid. |
7 | Multiple constraints may be provided. If none apply, then use the default value provided for the property. |
For more details on the syntax of conditions, see Syntax for conditions below.
Syntax for conditions
The value of the condition
property of a constraint is a string representing a single expression in the eForms expression language (EFX).
This expression is made of two parts:
-
The context under which the expression is evaluated. It’s often the parent node of the field.
-
The boolean expression itself.
Field data types
The possible technical values for a field type are:
id
|
string representing an identifier (may have an associated |
id-ref
|
string representing a reference to an identifier (has an associated |
indicator
|
boolean (true or false) |
integer
|
whole-valued positive number |
number
|
numerical value, with optional decimal places. |
amount
|
monetary amount, comprised of a numerical value and a currency |
measure
|
duration expressed using a numerical value and a unit |
code
|
string representing a concept in a code list |
date
|
date, always with time zone |
time
|
time, always with time zone |
email
|
string representing an e-mail address |
phone
|
string representing a phone number |
url
|
string representing a URL |
text
|
language-independent string |
text-multilingual
|
string that can be translated into multiple languages |