1.1 --- a/data/dictionary.xsd	Mon Jun 22 21:59:38 2020 +0200
     1.2 +++ b/data/dictionary.xsd	Mon Jun 22 23:11:14 2020 +0200
     1.3 @@ -25,8 +25,18 @@
     1.4  
     1.5  	<xs:complexType name="dictionaryType">
     1.6  		<xs:sequence>
     1.7 +			<xs:element name="id" type="ID"  minOccurs="0" maxOccurs="1"/>
     1.8  			<xs:element name="tags" type="tagsDefinitionType"  minOccurs="0" maxOccurs="1"/>
     1.9 -			<xs:element name="concept" type="conceptType"  minOccurs="0" maxOccurs="unbounded"/>
    1.10 +			<xs:element name="concept" type="conceptType"  minOccurs="0" maxOccurs="unbounded">
    1.11 +				<xs:annotation>
    1.12 +					<xs:documentation>
    1.13 +						Concept is an item of a dictionary – a term.
    1.14 +						If an abbreviation or a word have two different meanings
    1.15 +						it is two different concepts i.e. different meaning should not be mixed in a single concept.
    1.16 +						Example: CLI (command-line interface) and CLI (call level interface) are two different concepts.
    1.17 +					</xs:documentation>
    1.18 +				</xs:annotation>
    1.19 +			</xs:element>
    1.20  		</xs:sequence>
    1.21  	</xs:complexType>
    1.22  	
    1.23 @@ -37,13 +47,29 @@
    1.24  	</xs:complexType>
    1.25  	
    1.26  	<xs:complexType name="tagDefinitionType">
    1.27 -		<xs:attribute name="id" type="xs:string"/>
    1.28 +		<xs:attribute name="id" type="xs:string">
    1.29 +			<xs:annotation>
    1.30 +				<xs:documentation>
    1.31 +					Tag IDs are not globally unique
    1.32 +					(they are short and simple, so they can be easily added to concepts while editing the document by hand)
    1.33 +					so when the disctionary is merged into another XML document, theese IDs should be prefixed e.g. with the dictionary ID.
    1.34 +				</xs:documentation>
    1.35 +			</xs:annotation>
    1.36 +		</xs:attribute>
    1.37  		<xs:attribute name="name" type="xs:string"/>
    1.38  		<xs:attribute name="description" type="xs:string"/>
    1.39  	</xs:complexType>
    1.40  	
    1.41  	<xs:complexType name="conceptType">
    1.42  		<xs:sequence>
    1.43 +			<xs:element name="id" type="ID"  minOccurs="0" maxOccurs="1">
    1.44 +				<xs:annotation>
    1.45 +					<xs:documentation>
    1.46 +						This should be globally unique ID of the concept.
    1.47 +						Concepts shared among multiple dictionaries should have same ID.
    1.48 +					</xs:documentation>
    1.49 +				</xs:annotation>
    1.50 +			</xs:element>
    1.51  			<xs:element name="term" type="termType" minOccurs="1" maxOccurs="unbounded"/>
    1.52  			<xs:element name="explanation" type="explanationType"/>
    1.53  			<xs:element name="tag" type="tagRefType"  minOccurs="0" maxOccurs="unbounded"/>
    1.54 @@ -77,5 +103,18 @@
    1.55  	<xs:simpleType name="tagRefType">
    1.56  		<xs:restriction base="xs:string"/>
    1.57  	</xs:simpleType>
    1.58 +	
    1.59 +	<xs:simpleType name="ID">
    1.60 +		<xs:annotation>
    1.61 +			<xs:documentation>
    1.62 +				UUID, but must start with a letter, to comply with XML ID rules;
    1.63 +				use e.g. uuidgen | grep ^[a-f];
    1.64 +				Never reuse the ID if one chapter/item is removed and another with different meaning is added.
    1.65 +			</xs:documentation>
    1.66 +		</xs:annotation>
    1.67 +		<xs:restriction base="xs:ID">
    1.68 +			<xs:pattern value="[a-f][a-f0-9]{7}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}"/>
    1.69 +		</xs:restriction>
    1.70 +	</xs:simpleType>
    1.71  
    1.72  </xs:schema>
    1.73 \ No newline at end of file