From a63d08d972a45ae2449702c3539824dfa7b89590 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kat=20March=C3=A1n?= <kzm@zkat.tech>
Date: Wed, 1 Sep 2021 22:04:28 -0700
Subject: [PATCH] add type annotation info to spec

Fixes: https://github.com/kdl-org/kdl/issues/106
---
 SPEC.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 74 insertions(+), 1 deletion(-)

diff --git a/SPEC.md b/SPEC.md
index cfb65cf..4cfaea0 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -189,6 +189,78 @@ A value is either: a [String](#string), a [Raw String](#raw-string), a
 Values _MUST_ be either [Arguments](#argument) or values of
 [Properties](#property).
 
+Values _MAY_ be prefixed by a single [Type Annotation](#type-annotation).
+
+### Type Annotation
+
+A type annotation is a prefix to any [Value](#value) that includes a
+_suggestion_ of what type the value is _intended_ to be treated as.
+
+Type annotations are written as a set of `(` and `)` with a single
+[Identifier](#identifier) in it. Any valid identifier is considered a valid
+type annotation. There must be no whitespace between a type annotation and its
+associated Value.
+
+KDL does not specify any restrictions on what implementations might do with
+these annotations. They are free to ignore them, or use them to make decisions
+about how to interpret a value.
+
+Additionally, the following type annotations MAY be recognized by KDL parsers
+and, if used, SHOULD interpret these types as follows:
+
+#### Reserved Type Annotations for Numbers Without Decimals:
+
+Signed integers of various sizes (the number is the bit size):
+
+* `i8`
+* `i16`
+* `i32`
+* `i64`
+
+Unsigned integers of various sizes (the number is the bit size):
+
+* `u8`
+* `u16`
+* `u32`
+* `u64`
+
+Platform-dependent integer types, both signed and unsigned:
+
+* `isize`
+* `usize`
+
+IEEE 754 floating point numbers, both single (32) and double (64) precision:
+
+* `f32`
+* `f64`
+
+#### Reserved Type Annotations for Strings:
+
+* `date-time`: ISO8601 date/time format.
+* `time`: "Time" section of ISO8601.
+* `date`: "Date" section of ISO8601.
+* `email`: RFC5302 email address.
+* `idn-email`: RFC6531 internationalized email address.
+* `hostname`: RFC1132 internet hostname.
+* `idn-hostname`: RFC5890 internationalized internet hostname.
+* `ipv4`: RFC2673 dotted-quad IPv4 address.
+* `ipv6`: RFC2373 IPv6 address.
+* `uri`: RFC3986 URI.
+* `uri-reference`: RFC3986 URI Reference.
+* `iri`: RFC3987 Internationalized Resource Identifier.
+* `iri-reference`: RFC3987 Internationalized Resource Identifier Reference.
+* `uri-template`: RFC6570 URI Template.
+* `uuid`: RFC4122 UUID.
+* `regex`: Regular expression. Specific patterns may be implementation-dependent.
+* `base64`: A Base64-encoded string, denoting arbitrary binary data.
+
+#### Examples
+
+```kdl
+node (u8)123
+node prop=(regex)".*"
+```
+
 ### String
 
 Strings in KDL represent textual [Values](#value). They are delimited by `"`
@@ -338,7 +410,8 @@ bare-identifier := ((identifier-char - digit - sign) identifier-char* | sign ((i
 identifier-char := unicode - linespace - [\/(){}<>;[]=,"]
 keyword := boolean | 'null'
 prop := identifier '=' value
-value := string | number | keyword
+value := (type ws*)? (string | number | keyword)
+type := '(' identifier ')'
 
 string := raw-string | escaped-string
 escaped-string := '"' character* '"'