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)
    "xsdSequenceOrder" : [ { "cbc:RegulatoryDomain" : 18 } ], (7)
    "type" : "code", (8)
    "legalType" : "CODE", (9)
    "maxLength" : 400, (10)
    "repeatable" : { (11)
      "value" : false
    },
    "codeList" : { (12)
      "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",
    "xsdSequenceOrder" : [ { "cbc:ID" : 2 } ],
    "type" : "id",
    "idScheme" : "LOT", (13)
    "legalType" : "IDENTIFIER",
    "repeatable" : {
      "value" : false,
      "severity" : "ERROR"
    },
    "forbidden" : { (14)
      "value" : false,
      "severity" : "ERROR",
      "constraints" : [ {
        "noticeTypes" : [ "1", "2", "3", "4", "5", "6", "X01", "X02" ],
        "value" : true,
        "severity" : "ERROR"
      } ]
    },
    "mandatory" : { (15)
      "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" : { (16)
      "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",
    "xsdSequenceOrder" : [ { "efac:TenderLot" : 14 }, { "cbc:ID" : 1 } ],
    "type" : "id-ref",
    "idSchemes" : [ "LOT", "GLO" ], (17)
    "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 Position of each XML element relative to its siblings. See below for details.
8 Technical data type of the field.
9 Data type of the business term, as indicated in the eForms Regulation.
10 Maximum number of characters allowed in the value of the field, optional.
11 Indicates if the field can appear more than once inside its container
12 Identifier of the code list from which the field value must belong. Applicable only for fields of type "code" or "internal-code"
13 Identifier scheme used by a field with "type" : "id".
14 This property provides information on when a field’s presence is forbidden.
15 This property provides information on when a field’s value is mandatory.
16 A RegEx pattern the field’s value must match.
17 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 xmlStructure section of fields.json. See XML Structure.

name

The name of the field. It is provided to improve readability of the fields.json. In your applications you should the appropriate label for the field.

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 parentNodeId.

xpathRelative

The XPath of the field relative to its parent node. See parentNodeId.

xsdSequenceOrder

This indicates, for each XML element that is part of xpathRelative, the position that this element should have relative to its siblings in order to have an XML instance valid against the XML Schema. This information is extracted from the definition of the corresponding complex type in the XSD files.

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 id. Indicates the identifier scheme for this id field (e.g. "TPO" for Touch Point).

schemeName

Applicable only to fields of type id. Indicates the value that should be indicated for this field in the schemeName attribute in the XML.

idSchemes

Applicable only to fields of type id-ref. Provides an array of valid identifier schemes that this id-ref field can reference.

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 the repeatable 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 the mandatory property. If a field is forbidden, then it should not be present in the notice regardless of the value of its mandatory 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 and canRemove is true.

Example 1. Dynamic property value example

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 idScheme)

id-ref

string representing a reference to an identifier (has an associated idSchemes)

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