# HG changeset patch
# User František Kučera <franta-hg@frantovo.cz>
# Date 1592860274 -7200
# Node ID 5c878a53d3ed122fa789d3ec3216104d6adb0b1a
# Parent  a9f1ba45124735aaa87e5bfeabbbad144f1c482b
add dictionary and concept IDs + some documentation

diff -r a9f1ba451247 -r 5c878a53d3ed data/dictionary.xml
--- a/data/dictionary.xml	Mon Jun 22 21:59:38 2020 +0200
+++ b/data/dictionary.xml	Mon Jun 22 23:11:14 2020 +0200
@@ -14,6 +14,8 @@
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 -->
 <dictionary xmlns="https://telco.frantovo.cz/xmlns/dictionary">
+	
+	<id>fca6b6ec-34dd-4cb2-83a3-d1b8ceccb296</id>
 
 	<tags>
 		<tag id="acision" name="Acision" description="comes from Acision or is specific for this company"/>
diff -r a9f1ba451247 -r 5c878a53d3ed data/dictionary.xsd
--- a/data/dictionary.xsd	Mon Jun 22 21:59:38 2020 +0200
+++ b/data/dictionary.xsd	Mon Jun 22 23:11:14 2020 +0200
@@ -25,8 +25,18 @@
 
 	<xs:complexType name="dictionaryType">
 		<xs:sequence>
+			<xs:element name="id" type="ID"  minOccurs="0" maxOccurs="1"/>
 			<xs:element name="tags" type="tagsDefinitionType"  minOccurs="0" maxOccurs="1"/>
-			<xs:element name="concept" type="conceptType"  minOccurs="0" maxOccurs="unbounded"/>
+			<xs:element name="concept" type="conceptType"  minOccurs="0" maxOccurs="unbounded">
+				<xs:annotation>
+					<xs:documentation>
+						Concept is an item of a dictionary – a term.
+						If an abbreviation or a word have two different meanings
+						it is two different concepts i.e. different meaning should not be mixed in a single concept.
+						Example: CLI (command-line interface) and CLI (call level interface) are two different concepts.
+					</xs:documentation>
+				</xs:annotation>
+			</xs:element>
 		</xs:sequence>
 	</xs:complexType>
 	
@@ -37,13 +47,29 @@
 	</xs:complexType>
 	
 	<xs:complexType name="tagDefinitionType">
-		<xs:attribute name="id" type="xs:string"/>
+		<xs:attribute name="id" type="xs:string">
+			<xs:annotation>
+				<xs:documentation>
+					Tag IDs are not globally unique
+					(they are short and simple, so they can be easily added to concepts while editing the document by hand)
+					so when the disctionary is merged into another XML document, theese IDs should be prefixed e.g. with the dictionary ID.
+				</xs:documentation>
+			</xs:annotation>
+		</xs:attribute>
 		<xs:attribute name="name" type="xs:string"/>
 		<xs:attribute name="description" type="xs:string"/>
 	</xs:complexType>
 	
 	<xs:complexType name="conceptType">
 		<xs:sequence>
+			<xs:element name="id" type="ID"  minOccurs="0" maxOccurs="1">
+				<xs:annotation>
+					<xs:documentation>
+						This should be globally unique ID of the concept.
+						Concepts shared among multiple dictionaries should have same ID.
+					</xs:documentation>
+				</xs:annotation>
+			</xs:element>
 			<xs:element name="term" type="termType" minOccurs="1" maxOccurs="unbounded"/>
 			<xs:element name="explanation" type="explanationType"/>
 			<xs:element name="tag" type="tagRefType"  minOccurs="0" maxOccurs="unbounded"/>
@@ -77,5 +103,18 @@
 	<xs:simpleType name="tagRefType">
 		<xs:restriction base="xs:string"/>
 	</xs:simpleType>
+	
+	<xs:simpleType name="ID">
+		<xs:annotation>
+			<xs:documentation>
+				UUID, but must start with a letter, to comply with XML ID rules;
+				use e.g. uuidgen | grep ^[a-f];
+				Never reuse the ID if one chapter/item is removed and another with different meaning is added.
+			</xs:documentation>
+		</xs:annotation>
+		<xs:restriction base="xs:ID">
+			<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}"/>
+		</xs:restriction>
+	</xs:simpleType>
 
 </xs:schema>
\ No newline at end of file