diff --git a/src/vcard.nim b/src/vcard.nim
index b6acb0f..0d2ac68 100644
--- a/src/vcard.nim
+++ b/src/vcard.nim
@@ -1,3 +1,66 @@
-import vcard/vcard3
+# vCard 3.0 and 4.0 Nim implementation
+# © 2022 Jonathan Bernard
 
-export vcard3
+## The `vcard` module implements a high-performance vCard parser for both
+## versions 3.0 (defined by RFCs [2425][rfc2425] and  [2426][rfc2426]) and 4.0
+## (defined by RFC [6350][rfc6350])
+##
+## [rfc2425]: https://tools.ietf.org/html/rfc2425
+## [rfc2426]: https://tools.ietf.org/html/rfc2426
+## [rfc6350]: https://tools.ietf.org/html/rfc6350
+import std/[streams, unicode]
+
+import ./vcard/private/[common, lexer]
+import ./vcard/[vcard3, vcard4]
+
+export vcard3, vcard4
+export common.VC_XParam,
+       common.VCardParsingError,
+       common.VCardVersion,
+       common.VCard
+
+proc add[T](vc: VCard, content: varargs[T]): void =
+  if vc.parsedVersion == VCardV3: add(cast[VCard3](vc), content)
+  else: add(cast[VCard4](vc), content)
+
+proc readVCard*(p: var VCardParser): VCard =
+  # Read the preamble
+  discard p.readGroup
+  p.expect("begin:vcard" & CRLF)
+
+  # Look for the version tag
+  p.setBookmark
+  discard p.readGroup
+  if p.isNext("version:4.0"):
+    result = VCard4()
+    result.parsedVersion = VCardV4
+  else:
+    result = VCard3()
+    result.parsedVersion = VCardV3
+  p.returnToBookmark
+
+  # VCard3 3.0 allows arbitrarily many empty lines after BEGIN and END
+  if result.parsedVersion == VCardV3:
+    while (p.skip(CRLF, true)): discard
+    for content in vcard3.parseContentLines(p): result.add(content)
+    while (p.skip(CRLF, true)): discard
+
+  else:
+    for content in vcard4.parseContentLines(p): result.add(content)
+
+  if result.parsedVersion == VCardV3:
+    while (p.skip(CRLF, true)): discard
+
+proc parseVCards*(input: Stream, filename = "input"): seq[VCard] =
+  var p: VCardParser
+  p.filename = filename
+  lexer.open(p, input)
+
+  # until EOF
+  while p.peek != '\0': result.add(p.readVCard)
+
+proc parseVCards*(content: string, filename = "input"): seq[VCard] =
+  parseVCards(newStringStream(content), filename)
+
+proc parseVCardsFromFile*(filepath: string): seq[VCard] =
+  parseVCards(newFileStream(filepath, fmRead), filepath)
diff --git a/src/vcard/private/common.nim b/src/vcard/private/common.nim
new file mode 100644
index 0000000..bf0fb02
--- /dev/null
+++ b/src/vcard/private/common.nim
@@ -0,0 +1,240 @@
+import std/[macros, options, strutils, unicode]
+import zero_functional
+from std/sequtils import toSeq
+import ./lexer
+
+type
+  VCardVersion* = enum VCardV3 = "3.0", VCardV4 = "4.0"
+
+  VCardParser* = object of VCardLexer
+    filename*: string
+
+  VCParam* = tuple[name: string, values: seq[string]]
+
+  VCardParsingError* = object of ValueError
+
+  VC_XParam* = tuple[name, value: string]
+
+  VCard* = ref object of RootObj
+    parsedVersion*: VCardVersion
+
+const CRLF* = "\r\n"
+const WSP* = {' ', '\t'}
+const DIGIT* = { '0'..'9' }
+const ALPHA_NUM* = { 'a'..'z', 'A'..'Z', '0'..'9' }
+const NON_ASCII* = { '\x80'..'\xFF' }
+const QSAFE_CHARS* = WSP + { '\x21', '\x23'..'\x7E' } + NON_ASCII
+const SAFE_CHARS* = WSP + { '\x21', '\x23'..'\x2B', '\x2D'..'\x39', '\x3C'..'\x7E' } + NON_ASCII
+const VALUE_CHAR* = WSP + { '\x21'..'\x7E' } + NON_ASCII
+
+# Internal Utility/Implementation
+# =============================================================================
+
+template findAll*[T, VCT](c: openarray[VCT]): seq[T] =
+  c.filterIt(it of typeof(T)).mapIt(cast[T](it))
+
+template findFirst*[T, VCT](c: openarray[VCT]): Option[T] =
+  let found = c.filterIt(it of typeof(T)).mapIt(cast[T](it))
+  if found.len > 0: some(found[0])
+  else: none[T]()
+
+macro assignFields*(assign: untyped, fields: varargs[untyped]): untyped =
+  result = assign
+
+  for f in fields:
+    let exp = newNimNode(nnkExprColonExpr)
+    exp.add(f, f)
+    result.add(exp)
+
+# Output
+# =============================================================================
+
+func serialize*(s: seq[VC_XParam]): string =
+  result = ""
+  for x in s: result &= ";" & x.name & "=" & x.value
+
+# Parsing
+# =============================================================================
+
+proc error*(p: VCardParser, msg: string) =
+  raise newException(VCardParsingError, "$1($2, $3) Error: $4] " %
+    [ p.filename, $p.lineNumber, $p.getColNumber(p.pos), msg ])
+
+proc isNext*[T](p: var T, expected: string, caseSensitive = false): bool =
+  result = true
+  p.setBookmark
+
+  if caseSensitive:
+    for ch in expected:
+      if p.read != ch:
+        result = false
+        break
+
+  else:
+    for rune in expected.runes:
+      if p.readRune.toLower != rune.toLower:
+        result = false
+        break
+
+  p.returnToBookmark
+
+proc expect*[T](p: var T, expected: string, caseSensitive = false) =
+  p.setBookmark
+
+  if caseSensitive:
+    for ch in expected:
+      if p.read != ch:
+        p.error("expected '$1' but found '$2'" %
+          [expected, p.readSinceBookmark])
+
+  else:
+    for rune in expected.runes:
+      if p.readRune.toLower != rune.toLower:
+        p.error("expected '$1' but found '$2'" %
+          [ expected, p.readSinceBookmark ])
+
+  p.unsetBookmark
+
+proc readGroup*[T](p: var T): Option[string] =
+  ## All VCARD content items can be optionally prefixed with a group name. This
+  ## scans the input to see if there is a group defined at the current read
+  ## location. If there is a valid group, the group name is returned and the
+  ## read position is advanced past the '.' to the start of the content type
+  ## name. If there is not a valid group the read position is left unchanged.
+
+  p.setBookmark
+  var ch = p.read
+  while ALPHA_NUM.contains(ch): ch = p.read
+
+  if (ch == '.'):
+    result = some(readSinceBookmark(p)[0..^2])
+    p.unsetBookmark
+  else:
+    result = none[string]()
+    p.returnToBookmark
+
+proc readName*(p: var VCardParser): string =
+  ## Read a name from the current read position or error. As both content types
+  ## and paramaters use the same definition for valid names, this method is
+  ## used to read in both.
+  p.setBookmark
+  let validChars = ALPHA_NUM + {'-'}
+  while validChars.contains(p.peek): discard p.read
+  result = p.readSinceBookmark.toUpper()
+  if result.len == 0:
+    p.error("expected to read a name but found '$1'" % [$p.peek])
+  p.unsetBookmark
+
+proc readValue*(p: var VCardParser): string =
+  ## Read a content value at the current read position.
+  p.setBookmark
+  while VALUE_CHAR.contains(p.peek): discard p.read
+  result = p.readSinceBookmark
+  p.unsetBookmark
+
+proc skip*(p: var VCardParser, count: int): bool =
+  for _ in 0..<count: discard p.read
+
+proc skip*(p: var VCardParser, expected: string, caseSensitive = false): bool =
+  p.setBookmark
+  if caseSensitive:
+    for ch in expected:
+      if p.read != ch:
+        p.returnToBookmark
+        return false
+
+  else:
+    for rune in expected.runes:
+      if p.readRune.toLower != rune.toLower:
+        p.returnToBookmark
+        return false
+
+  p.unsetBookmark
+  return true
+
+proc existsWithValue*(
+    params: openarray[VCParam],
+    name, value: string,
+    caseSensitive = false
+  ): bool =
+
+  ## Determine if the given parameter exists and has the expected value. By
+  ## default, value checks are not case-sensitive, as most VCard3 values are not
+  ## defined as being case-sensitive.
+
+  let ps = params.toSeq
+
+  if caseSensitive:
+    ps --> exists(
+      it.name == name and
+      it.values.len == 1 and
+      it.values[0] == value)
+  else:
+    ps --> exists(
+      it.name == name and
+      it.values.len == 1 and
+      it.values[0].toLower == value.toLower)
+
+proc getMultipleValues*(
+    params: openarray[VCParam],
+    name: string
+  ): seq[string] =
+
+  ## Get all of the values for a given parameter in a single list. There are
+  ## two patterns for multi-valued parameters defined in the VCard3 RFCs:
+  ##
+  ##   - TYPE=work,cell,voice
+  ##   - TYPE=work;TYPE=cell;TYPE=voice
+  ##
+  ## Parameter values can often be specific using both patterns. This method
+  ## joins all defined values regardless of the pattern used to define them.
+
+  let ps = params.toSeq
+  ps -->
+    filter(it.name == name).
+    map(it.values).
+    flatten()
+
+proc getSingleValue*(
+    params: openarray[VCParam],
+    name: string
+  ): Option[string] =
+  ## Get the first single value defined for a parameter.
+  #
+  # Many parameters only support a single value, depending on the content type.
+  # In order to support multi-valued parameters our implementation stores all
+  # parameters as seq[string]. This function is a convenience around that.
+
+  let ps = params.toSeq
+  let foundParam = ps --> find(it.name == name)
+
+  if foundParam.isSome and foundParam.get.values.len > 0:
+    return some(foundParam.get.values[0])
+  else:
+    return none[string]()
+
+proc validateNoParameters*(
+    p: VCardParser,
+    params: openarray[VCParam],
+    name: string
+  ) =
+
+  ## Error unless there are no defined parameters
+  if params.len > 0:
+    p.error("no parameters allowed on the $1 content type" % [name])
+
+proc validateRequiredParameters*(
+    p: VCardParser,
+    params: openarray[VCParam],
+    expectations: openarray[tuple[name: string, value: string]]
+  ) =
+
+  ## Some content types have specific allowed parameters. For example, the
+  ## SOURCE content type requires that the VALUE parameter be set to "uri" if
+  ## it is present. This will error if given parameters are present with
+  ## different values that expected.
+
+  for (n, v) in expectations:
+    let pv = params.getSingleValue(n)
+    if pv.isSome and pv.get != v:
+      p.error("parameter '$1' must have the value '$2'" % [n, v])
diff --git a/src/vcard/private/parsercommon.nim b/src/vcard/private/parsercommon.nim
deleted file mode 100644
index 908d50c..0000000
--- a/src/vcard/private/parsercommon.nim
+++ /dev/null
@@ -1,40 +0,0 @@
-import options, strutils
-import ./lexer
-
-const WSP* = {' ', '\t'}
-const ALPHA_NUM* = { 'a'..'z', 'A'..'Z', '0'..'9' }
-
-proc expect*[T](p: var T, expected: string, caseSensitive = false) =
-  p.setBookmark
-
-  if caseSensitive:
-    for ch in expected:
-      if p.read != ch:
-        p.error("expected '$1' but found '$2'" %
-          [expected, p.readSinceBookmark])
-
-  else:
-    for rune in expected.runes:
-      if p.readRune.toLower != rune.toLower:
-        p.error("expected '$1' but found '$2'" %
-          [ expected, p.readSinceBookmark ])
-
-  p.unsetBookmark
-
-proc readGroup*[T](p: var T): Option[string] =
-  ## All VCARD content items can be optionally prefixed with a group name. This
-  ## scans the input to see if there is a group defined at the current read
-  ## location. If there is a valid group, the group name is returned and the
-  ## read position is advanced past the '.' to the start of the content type
-  ## name. If there is not a valid group the read position is left unchanged.
-
-  p.setBookmark
-  var ch = p.read
-  while ALPHA_NUM.contains(ch): ch = p.read
-
-  if (ch == '.'):
-    result = some(readSinceBookmark(p)[0..^2])
-    p.unsetBookmark
-  else:
-    result = none[string]()
-    p.returnToBookmark
diff --git a/src/vcard/vcard3.nim b/src/vcard/vcard3.nim
index dea32d1..5508058 100644
--- a/src/vcard/vcard3.nim
+++ b/src/vcard/vcard3.nim
@@ -1,4 +1,4 @@
-# vCard 3.0 and 4.0 Nm implementation
+# vCard 3.0 and 4.0 Nim implementation
 # © 2022 Jonathan Bernard
 
 ## The `vcard` module implements a high-performance vCard parser for both
@@ -14,25 +14,25 @@ import std/[base64, macros, options, sequtils, streams, strutils, times,
 
 import zero_functional
 
-import ./vcard/private/[util, lexer]
+import ./private/[common, lexer, util]
 
 type
   VC3_ValueTypes = enum
-    vtUri = "URI",
-    vtText = "TEXT",
-    vtPText = "PTEXT",
-    vtDate = "DATE",
-    vtTime = "TIME",
-    vtDateTime = "DATE-TIME",
-    vtInteger = "INTEGER",
-    vtBoolean = "BOOLEAN",
-    vtFloat = "FLOAT",
-    vtBinary = "BINARY",
-    vtVCard = "VCARD"
-    vtPhoneNumber = "PHONE-NUMBER"
-    vtUtcOffset = "UTC-OFFSET"
+    vtUri = "uri",
+    vtText = "text",
+    vtPText = "ptext",
+    vtDate = "date",
+    vtTime = "time",
+    vtDateTime = "date-time",
+    vtInteger = "integer",
+    vtBoolean = "boolean",
+    vtFloat = "float",
+    vtBinary = "binary",
+    vtVCard = "vcard"
+    vtPhoneNumber = "phone-number"
+    vtUtcOffset = "utc-offset"
 
-  VC3_ContentNames = enum
+  VC3_PropertyNames = enum
     cnName = "NAME"
     cnProfile = "PROFILE"
     cnSource = "SOURCE"
@@ -65,22 +65,18 @@ type
     cnClass = "CLASS"
     cnKey = "KEY"
 
-  VC3_XParam* = tuple[name, value: string]
-
-  VC3_Content* = ref object of RootObj
-    contentId*: int
+  VC3_Property* = ref object of RootObj
+    propertyId: int
     group*: Option[string]
     name*: string
 
-  VC3_ContentList* = openarray[VC3_Content]
-
-  VC3_SimpleTextContent* = ref object of VC3_Content
+  VC3_SimpleTextProperty* = ref object of VC3_Property
     value*: string
     isPText*: bool # true if VALUE=ptext, false by default
     language*: Option[string]
-    xParams: seq[VC3_XParam]
+    xParams: seq[VC_XParam]
 
-  VC3_BinaryContent* = ref object of VC3_Content
+  VC3_BinaryProperty* = ref object of VC3_Property
     valueType*: Option[string] # binary / uri. Stored separately from ENCODING
                                # (captured in the isInline field) because the
                                # VALUE parameter is not set by default, but is
@@ -91,20 +87,20 @@ type
                                # binary-encoded object, which is stored here.
     isInline*: bool # true if ENCODING=b, false by default
 
-  VC3_Name* = ref object of VC3_Content
+  VC3_Name* = ref object of VC3_Property
     value*: string
 
-  VC3_Profile* = ref object of VC3_Content
+  VC3_Profile* = ref object of VC3_Property
 
-  VC3_Source* = ref object of VC3_Content
+  VC3_Source* = ref object of VC3_Property
     valueType*: Option[string]  # uri
     value*: string # URI
     context*: Option[string]
-    xParams*: seq[VC3_XParam]
+    xParams*: seq[VC_XParam]
 
-  VC3_Fn* = ref object of VC3_SimpleTextContent
+  VC3_Fn* = ref object of VC3_SimpleTextProperty
 
-  VC3_N* = ref object of VC3_Content
+  VC3_N* = ref object of VC3_Property
     family*: seq[string]
     given*: seq[string]
     additional*: seq[string]
@@ -112,13 +108,13 @@ type
     suffixes*: seq[string]
     language*: Option[string]
     isPText*: bool # true if VALUE=ptext, false by default
-    xParams*: seq[VC3_XParam]
+    xParams*: seq[VC_XParam]
 
-  VC3_Nickname* = ref object of VC3_SimpleTextContent
+  VC3_Nickname* = ref object of VC3_SimpleTextProperty
 
-  VC3_Photo* = ref object of VC3_BinaryContent
+  VC3_Photo* = ref object of VC3_BinaryProperty
 
-  VC3_Bday* = ref object of VC3_Content
+  VC3_Bday* = ref object of VC3_Property
     valueType*: Option[string] # date / date-time
     value*: DateTime
 
@@ -132,7 +128,7 @@ type
     atWork = "WORK"
     atPref = "PREF"
 
-  VC3_Adr* = ref object of VC3_Content
+  VC3_Adr* = ref object of VC3_Property
     adrType*: seq[string]
     poBox*: string
     extendedAdr*: string
@@ -143,9 +139,9 @@ type
     country*: string
     isPText*: bool # true if VALUE=ptext, false by default
     language*: Option[string]
-    xParams*: seq[VC3_XParam]
+    xParams*: seq[VC_XParam]
 
-  VC3_Label* = ref object of VC3_SimpleTextContent
+  VC3_Label* = ref object of VC3_SimpleTextProperty
     adrType*: seq[string]
 
   VC3_TelTypes* = enum
@@ -164,7 +160,7 @@ type
     ttVideo = "VIDEO",
     ttPcs = "PCS"
 
-  VC3_Tel* = ref object of VC3_Content
+  VC3_Tel* = ref object of VC3_Property
     telType*: seq[string]
     value*: string
 
@@ -172,100 +168,84 @@ type
     etInternet = "INTERNET",
     etX400 = "X400"
 
-  VC3_Email* = ref object of VC3_Content
+  VC3_Email* = ref object of VC3_Property
     emailType*: seq[string]
     value*: string
 
-  VC3_Mailer* = ref object of VC3_SimpleTextContent
+  VC3_Mailer* = ref object of VC3_SimpleTextProperty
 
-  VC3_TZ* = ref object of VC3_Content
+  VC3_TZ* = ref object of VC3_Property
     value*: string
     isText*: bool # true if VALUE=text, false by default
 
-  VC3_Geo* = ref object of VC3_Content
+  VC3_Geo* = ref object of VC3_Property
     lat*, long*: float
 
-  VC3_Title* = ref object of VC3_SimpleTextContent
+  VC3_Title* = ref object of VC3_SimpleTextProperty
 
-  VC3_Role* = ref object of VC3_SimpleTextContent
+  VC3_Role* = ref object of VC3_SimpleTextProperty
 
-  VC3_Logo* = ref object of VC3_BinaryContent
+  VC3_Logo* = ref object of VC3_BinaryProperty
 
-  VC3_Agent* = ref object of VC3_Content
+  VC3_Agent* = ref object of VC3_Property
     value*: string  # either an escaped vCard object, or a URI
     isInline*: bool # false if VALUE=uri, true by default
 
-  VC3_Org* = ref object of VC3_Content
+  VC3_Org* = ref object of VC3_Property
     value*: seq[string]
     isPText*: bool # true if VALUE=ptext, false by default
     language*: Option[string]
-    xParams*: seq[VC3_XParam]
+    xParams*: seq[VC_XParam]
 
-  VC3_Categories* = ref object of VC3_Content
+  VC3_Categories* = ref object of VC3_Property
     value*: seq[string]
     isPText*: bool # true if VALUE=ptext, false by default
     language*: Option[string]
-    xParams*: seq[VC3_XParam]
+    xParams*: seq[VC_XParam]
 
-  VC3_Note* = ref object of VC3_SimpleTextContent
+  VC3_Note* = ref object of VC3_SimpleTextProperty
 
-  VC3_Prodid* = ref object of VC3_SimpleTextContent
+  VC3_Prodid* = ref object of VC3_SimpleTextProperty
 
-  VC3_Rev* = ref object of VC3_Content
+  VC3_Rev* = ref object of VC3_Property
     valueType*: Option[string] # date / date-time
     value*: DateTime
 
-  VC3_SortString* = ref object of VC3_SimpleTextContent
+  VC3_SortString* = ref object of VC3_SimpleTextProperty
 
-  VC3_Sound* = ref object of VC3_BinaryContent
+  VC3_Sound* = ref object of VC3_BinaryProperty
 
-  VC3_UID* = ref object of VC3_Content
+  VC3_UID* = ref object of VC3_Property
     value*: string
 
-  VC3_URL* = ref object of VC3_Content
+  VC3_URL* = ref object of VC3_Property
     value*: string
 
-  VC3_Version* = ref object of VC3_Content
+  VC3_Version* = ref object of VC3_Property
     value*: string # 3.0
 
-  VC3_Class* = ref object of VC3_Content
+  VC3_Class* = ref object of VC3_Property
     value*: string
 
-  VC3_Key* = ref object of VC3_BinaryContent
+  VC3_Key* = ref object of VC3_BinaryProperty
     keyType*: Option[string] # x509 / pgp
 
-  VC3_XType* = ref object of VC3_SimpleTextContent
+  VC3_XType* = ref object of VC3_SimpleTextProperty
 
-  VCard3* = object
-    nextContentId: int
-    content*: seq[VC3_Content]
+  # TODO: implications of this being a ref now instead of a concrete object
+  VCard3* = ref object of VCard
+    nextPropertyId: int
+    content*: seq[VC3_Property]
 
-const CRLF = "\r\n"
 const DATE_FMT = "yyyy-MM-dd"
 const DATETIME_FMT = "yyyy-MM-dd'T'HH:mm:sszz"
 
 # Internal Utility/Implementation
 # =============================================================================
 
-template findAll[T](c: VC3_ContentList): seq[T] =
-  c.filterIt(it of typeof(T)).mapIt(cast[T](it))
-
-template findFirst[T](c: VC3_ContentList): Option[T] =
-  let found = c.filterIt(it of typeof(T)).mapIt(cast[T](it))
-  if found.len > 0: some(found[0])
-  else: none[T]()
-
-template takeContentId(vc3: var VCard3): int =
-  vc3.nextContentId += 1
-  vc3.nextContentId - 1
-
-macro assignFields(assign: untyped, fields: varargs[untyped]): untyped =
-  result = assign
-
-  for f in fields:
-    let exp = newNimNode(nnkExprColonExpr)
-    exp.add(f, f)
-    result.add(exp)
+template takePropertyId(vc3: VCard3): int =
+  vc3.nextPropertyId += 1
+  vc3.nextPropertyId - 1
 
 
 # Initializers
@@ -278,12 +258,12 @@ func newVC3_Source*(
   value: string,
   inclContext = false,
   inclValue = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Source =
 
   return assignFields(
     VC3_Source(
-      name: "SOURCE",
+      name: $cnSource,
       valueType: if inclValue: some("uri")
                  else: none[string](),
       context: if inclContext: some("word")
@@ -294,11 +274,11 @@ func newVC3_Fn*(
   value: string,
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Fn =
 
   return assignFields(
-    VC3_Fn(name: "FN"),
+    VC3_Fn(name: $cnFn),
     value, language, isPText, group, xParams)
 
 func newVC3_N*(
@@ -309,22 +289,22 @@ func newVC3_N*(
   suffixes: seq[string] = @[],
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_N =
 
   return assignFields(
-    VC3_N(name: "N"),
+    VC3_N(name: $cnN),
     family, given, additional, prefixes, suffixes, language, xParams)
 
 func newVC3_Nickname*(
   value: string,
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Nickname =
 
   return assignFields(
-    VC3_Nickname(name: "NICKNAME"),
+    VC3_Nickname(name: $cnNickname),
     value, language, isPText, group, xParams)
 
 func newVC3_Photo*(
@@ -335,7 +315,7 @@ func newVC3_Photo*(
   group = none[string]()): VC3_Photo =
 
   return assignFields(
-    VC3_Photo(name: "PHOTO"),
+    VC3_Photo(name: $cnPhoto),
     value, valueType, binaryType, isInline, group)
 
 func newVC3_Bday*(
@@ -343,7 +323,7 @@ func newVC3_Bday*(
   valueType = none[string](),
   group = none[string]()): VC3_Bday =
 
-    return assignFields(VC3_Bday(name: "BDAY"), value, valueType, group)
+    return assignFields(VC3_Bday(name: $cnBday), value, valueType, group)
 
 func newVC3_Adr*(
   adrType = @[$atIntl,$atPostal,$atParcel,$atWork],
@@ -357,10 +337,10 @@ func newVC3_Adr*(
   language = none[string](),
   isPText = false,
   group = none[string](),
-  xParams: seq[VC3_XParam] = @[]): VC3_Adr =
+  xParams: seq[VC_XParam] = @[]): VC3_Adr =
 
   return assignFields(
-    VC3_Adr(name: "ADR"),
+    VC3_Adr(name: $cnAdr),
     adrType, poBox, extendedAdr, streetAdr, locality, region, postalCode,
     country, isPText, language, group, xParams)
 
@@ -369,11 +349,11 @@ func newVC3_Label*(
   adrType = @[$atIntl,$atPostal,$atParcel,$atWork],
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Label =
 
   return assignFields(
-    VC3_Label(name: "LABEL"),
+    VC3_Label(name: $cnLabel),
     value, adrType, language, isPText, group, xParams)
 
 func newVC3_Tel*(
@@ -381,52 +361,52 @@ func newVC3_Tel*(
   telType = @[$ttVoice],
   group = none[string]()): VC3_Tel =
 
-  return assignFields(VC3_Tel(name: "TEL"), value, telType, group)
+  return assignFields(VC3_Tel(name: $cnTel), value, telType, group)
 
 func newVC3_Email*(
   value: string,
   emailType = @[$etInternet],
   group = none[string]()): VC3_Email =
 
-  return assignFields(VC3_Email(name: "EMAIL"), value, emailType, group)
+  return assignFields(VC3_Email(name: $cnEmail), value, emailType, group)
 
 func newVC3_Mailer*(
   value: string,
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Mailer =
 
   return assignFields(
-    VC3_Mailer(name: "MAILER"),
+    VC3_Mailer(name: $cnMailer),
     value, language, isPText, xParams, group)
 
 func newVC3_TZ*(value: string, isText = false, group = none[string]()): VC3_TZ =
-  return assignFields(VC3_TZ(name: "TZ"), value, isText, group)
+  return assignFields(VC3_TZ(name: $cnTz), value, isText, group)
 
 func newVC3_Geo*(lat, long: float, group = none[string]()): VC3_Geo =
-  return assignFields(VC3_Geo(name: "GEO"), lat, long, group)
+  return assignFields(VC3_Geo(name: $cnGeo), lat, long, group)
 
 func newVC3_Title*(
   value: string,
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Title =
 
   return assignFields(
-    VC3_Title(name: "TITLE"),
+    VC3_Title(name: $cnTitle),
     value, language, isPText, xParams, group)
 
 func newVC3_Role*(
   value: string,
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Role =
 
   return assignFields(
-    VC3_Role(name: "ROLE"),
+    VC3_Role(name: $cnRole),
     value, language, isPText, xParams, group)
 
 func newVC3_Logo*(
@@ -437,7 +417,7 @@ func newVC3_Logo*(
   group = none[string]()): VC3_Logo =
 
   return assignFields(
-    VC3_Logo(name: "LOGO"),
+    VC3_Logo(name: $cnLogo),
     value, valueType, binaryType, isInline, group)
 
 func newVC3_Agent*(
@@ -445,50 +425,50 @@ func newVC3_Agent*(
   isInline = true,
   group = none[string]()): VC3_Agent =
 
-  return VC3_Agent(name: "AGENT", isInline: isInline, group: group)
+  return VC3_Agent(name: $cnAgent, isInline: isInline, group: group)
 
 func newVC3_Org*(
   value: seq[string],
   isPText = false,
   language = none[string](),
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Org =
 
   return assignFields(
-    VC3_Org(name: "ORG"),
+    VC3_Org(name: $cnOrg),
     value, isPText, language, xParams, group)
 
 func newVC3_Categories*(
   value: seq[string],
   isPText = false,
   language = none[string](),
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Categories =
 
   return assignFields(
-    VC3_Categories(name: "CATEGORIES"),
+    VC3_Categories(name: $cnCategories),
     value, isPText, language, xParams, group)
 
 func newVC3_Note*(
   value: string,
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Note =
 
   return assignFields(
-    VC3_Note(name: "NOTE"),
+    VC3_Note(name: $cnNote),
     value, language, isPText, xParams, group)
 
 func newVC3_Prodid*(
   value: string,
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_Prodid =
 
   return assignFields(
-    VC3_Prodid(name: "PRODID"),
+    VC3_Prodid(name: $cnProdid),
     value, language, isPText, xParams, group)
 
 func newVC3_Rev*(
@@ -496,17 +476,17 @@ func newVC3_Rev*(
   valueType = none[string](),
   group = none[string]()): VC3_Rev =
 
-  return assignFields(VC3_Rev(name: "REV"), value, valueType, group)
+  return assignFields(VC3_Rev(name: $cnRev), value, valueType, group)
 
 func newVC3_SortString*(
   value: string,
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_SortString =
 
   return assignFields(
-    VC3_SortString(name: "SORTSTRING"),
+    VC3_SortString(name: $cnSortstring),
     value, language, isPText, xParams, group)
 
 func newVC3_Sound*(
@@ -517,20 +497,20 @@ func newVC3_Sound*(
   group = none[string]()): VC3_Sound =
 
   return assignFields(
-    VC3_Sound(name: "SOUND"),
+    VC3_Sound(name: $cnSound),
     value, valueType, binaryType, isInline, group)
 
 func newVC3_UID*(value: string, group = none[string]()): VC3_UID =
-  return VC3_UID(name: "UID", value: value, group: group)
+  return VC3_UID(name: $cnUid, value: value, group: group)
 
 func newVC3_URL*(value: string, group = none[string]()): VC3_URL =
-  return VC3_URL(name: "URL", value: value, group: group)
+  return VC3_URL(name: $cnUrl, value: value, group: group)
 
 func newVC3_Version*(group = none[string]()): VC3_Version =
-  return VC3_Version(name: "VERSION", value: "3.0", group: group)
+  return VC3_Version(name: $cnVersion, value: "3.0", group: group)
 
 func newVC3_Class*(value: string, group = none[string]()): VC3_Class =
-  return VC3_Class(name: "CLASS", value: value, group: group)
+  return VC3_Class(name: $cnClass, value: value, group: group)
 
 func newVC3_Key*(
   value: string,
@@ -540,7 +520,7 @@ func newVC3_Key*(
   group = none[string]()): VC3_Key =
 
   return assignFields(
-    VC3_Key(name: "KEY", binaryType: keyType),
+    VC3_Key(name: $cnKey, binaryType: keyType),
     value, valueType, keyType, isInline, group)
 
 func newVC3_XType*(
@@ -548,7 +528,7 @@ func newVC3_XType*(
   value: string,
   language = none[string](),
   isPText = false,
-  xParams: seq[VC3_XParam] = @[],
+  xParams: seq[VC_XParam] = @[],
   group = none[string]()): VC3_XType =
 
   if not name.startsWith("X-"):
@@ -561,652 +541,155 @@ func newVC3_XType*(
 # Accessors
 # =============================================================================
 
-func forGroup*(vc: VC3_ContentList, group: string): seq[VC3_Content] =
+func forGroup*(vc: openarray[VC3_Property], group: string): seq[VC3_Property] =
   return vc.filterIt(it.group.isSome and it.group.get == group)
 
-func groups*(vc: VC3_ContentList): seq[string] =
+func groups*(vc: openarray[VC3_Property]): seq[string] =
   result = @[]
   for c in vc:
     if c.group.isSome:
       let grp = c.group.get
       if not result.contains(grp): result.add(grp)
 
-func name*(c: VC3_ContentList): Option[VC3_Name] = findFirst[VC3_Name](c)
+func name*(c: openarray[VC3_Property]): Option[VC3_Name] = findFirst[VC3_Name](c)
 func name*(vc3: VCard3): Option[VC3_Name] = vc3.content.name
 
-func profile*(c: VC3_ContentList): Option[VC3_Profile] =
+func profile*(c: openarray[VC3_Property]): Option[VC3_Profile] =
   findFirst[VC3_Profile](c)
 func profile*(vc3: VCard3): Option[VC3_Profile] = vc3.content.profile
 
-func source*(c: VC3_ContentList): seq[VC3_Source] = findAll[VC3_Source](c)
+func source*(c: openarray[VC3_Property]): seq[VC3_Source] = findAll[VC3_Source](c)
 func source*(vc3: VCard3): seq[VC3_Source] = vc3.content.source
 
-func fn*(c: VC3_ContentList): VC3_Fn = findFirst[VC3_Fn](c).get
+func fn*(c: openarray[VC3_Property]): VC3_Fn = findFirst[VC3_Fn](c).get
 func fn*(vc3: VCard3): VC3_Fn = vc3.content.fn
 
-func n*(c: VC3_ContentList): VC3_N = findFirst[VC3_N](c).get
+func n*(c: openarray[VC3_Property]): VC3_N = findFirst[VC3_N](c).get
 func n*(vc3: VCard3): VC3_N = vc3.content.n
 
-func nickname*(c: VC3_ContentList): Option[VC3_Nickname] = findFirst[VC3_Nickname](c)
+func nickname*(c: openarray[VC3_Property]): Option[VC3_Nickname] = findFirst[VC3_Nickname](c)
 func nickname*(vc3: VCard3): Option[VC3_Nickname] = vc3.content.nickname
 
-func photo*(c: VC3_ContentList): seq[VC3_Photo] = findAll[VC3_Photo](c)
+func photo*(c: openarray[VC3_Property]): seq[VC3_Photo] = findAll[VC3_Photo](c)
 func photo*(vc3: VCard3): seq[VC3_Photo] = vc3.content.photo
 
-func bday*(c: VC3_ContentList): Option[VC3_Bday] = findFirst[VC3_Bday](c)
+func bday*(c: openarray[VC3_Property]): Option[VC3_Bday] = findFirst[VC3_Bday](c)
 func bday*(vc3: VCard3): Option[VC3_Bday] = vc3.content.bday
 
-func adr*(c: VC3_ContentList): seq[VC3_Adr] = findAll[VC3_Adr](c)
+func adr*(c: openarray[VC3_Property]): seq[VC3_Adr] = findAll[VC3_Adr](c)
 func adr*(vc3: VCard3): seq[VC3_Adr] = vc3.content.adr
 
-func label*(c: VC3_ContentList): seq[VC3_Label] = findAll[VC3_Label](c)
+func label*(c: openarray[VC3_Property]): seq[VC3_Label] = findAll[VC3_Label](c)
 func label*(vc3: VCard3): seq[VC3_Label] = vc3.content.label
 
-func tel*(c: VC3_ContentList): seq[VC3_Tel] = findAll[VC3_Tel](c)
+func tel*(c: openarray[VC3_Property]): seq[VC3_Tel] = findAll[VC3_Tel](c)
 func tel*(vc3: VCard3): seq[VC3_Tel] = vc3.content.tel
 
-func email*(c: VC3_ContentList): seq[VC3_Email] = findAll[VC3_Email](c)
+func email*(c: openarray[VC3_Property]): seq[VC3_Email] = findAll[VC3_Email](c)
 func email*(vc3: VCard3): seq[VC3_Email] = vc3.content.email
 
-func mailer*(c: VC3_ContentList): Option[VC3_Mailer] = findFirst[VC3_Mailer](c)
+func mailer*(c: openarray[VC3_Property]): Option[VC3_Mailer] = findFirst[VC3_Mailer](c)
 func mailer*(vc3: VCard3): Option[VC3_Mailer] = vc3.content.mailer
 
-func tz*(c: VC3_ContentList): Option[VC3_Tz] = findFirst[VC3_Tz](c)
+func tz*(c: openarray[VC3_Property]): Option[VC3_Tz] = findFirst[VC3_Tz](c)
 func tz*(vc3: VCard3): Option[VC3_Tz] = vc3.content.tz
 
-func geo*(c: VC3_ContentList): Option[VC3_Geo] = findFirst[VC3_Geo](c)
+func geo*(c: openarray[VC3_Property]): Option[VC3_Geo] = findFirst[VC3_Geo](c)
 func geo*(vc3: VCard3): Option[VC3_Geo] = vc3.content.geo
 
-func title*(c: VC3_ContentList): seq[VC3_Title] = findAll[VC3_Title](c)
+func title*(c: openarray[VC3_Property]): seq[VC3_Title] = findAll[VC3_Title](c)
 func title*(vc3: VCard3): seq[VC3_Title] = vc3.content.title
 
-func role*(c: VC3_ContentList): seq[VC3_Role] = findAll[VC3_Role](c)
+func role*(c: openarray[VC3_Property]): seq[VC3_Role] = findAll[VC3_Role](c)
 func role*(vc3: VCard3): seq[VC3_Role] = vc3.content.role
 
-func logo*(c: VC3_ContentList): seq[VC3_Logo] = findAll[VC3_Logo](c)
+func logo*(c: openarray[VC3_Property]): seq[VC3_Logo] = findAll[VC3_Logo](c)
 func logo*(vc3: VCard3): seq[VC3_Logo] = vc3.content.logo
 
-func agent*(c: VC3_ContentList): Option[VC3_Agent] = findFirst[VC3_Agent](c)
+func agent*(c: openarray[VC3_Property]): Option[VC3_Agent] = findFirst[VC3_Agent](c)
 func agent*(vc3: VCard3): Option[VC3_Agent] = vc3.content.agent
 
-func org*(c: VC3_ContentList): seq[VC3_Org] = findAll[VC3_Org](c)
+func org*(c: openarray[VC3_Property]): seq[VC3_Org] = findAll[VC3_Org](c)
 func org*(vc3: VCard3): seq[VC3_Org] = vc3.content.org
 
-func categories*(c: VC3_ContentList): Option[VC3_Categories] =
+func categories*(c: openarray[VC3_Property]): Option[VC3_Categories] =
   findFirst[VC3_Categories](c)
 func categories*(vc3: VCard3): Option[VC3_Categories] = vc3.content.categories
 
-func note*(c: VC3_ContentList): Option[VC3_Note] = findFirst[VC3_Note](c)
+func note*(c: openarray[VC3_Property]): Option[VC3_Note] = findFirst[VC3_Note](c)
 func note*(vc3: VCard3): Option[VC3_Note] = vc3.content.note
 
-func prodid*(c: VC3_ContentList): Option[VC3_Prodid] = findFirst[VC3_Prodid](c)
+func prodid*(c: openarray[VC3_Property]): Option[VC3_Prodid] = findFirst[VC3_Prodid](c)
 func prodid*(vc3: VCard3): Option[VC3_Prodid] = vc3.content.prodid
 
-func rev*(c: VC3_ContentList): Option[VC3_Rev] = findFirst[VC3_Rev](c)
+func rev*(c: openarray[VC3_Property]): Option[VC3_Rev] = findFirst[VC3_Rev](c)
 func rev*(vc3: VCard3): Option[VC3_Rev] = vc3.content.rev
 
-func sortstring*(c: VC3_ContentList): Option[VC3_SortString] =
+func sortstring*(c: openarray[VC3_Property]): Option[VC3_SortString] =
   findFirst[VC3_SortString](c)
 func sortstring*(vc3: VCard3): Option[VC3_SortString] = vc3.content.sortstring
 
-func sound*(c: VC3_ContentList): seq[VC3_Sound] = findAll[VC3_Sound](c)
+func sound*(c: openarray[VC3_Property]): seq[VC3_Sound] = findAll[VC3_Sound](c)
 func sound*(vc3: VCard3): seq[VC3_Sound] = vc3.content.sound
 
-func uid*(c: VC3_ContentList): Option[VC3_UID] = findFirst[VC3_UID](c)
+func uid*(c: openarray[VC3_Property]): Option[VC3_UID] = findFirst[VC3_UID](c)
 func uid*(vc3: VCard3): Option[VC3_UID] = vc3.content.uid
 
-func url*(c: VC3_ContentList): Option[VC3_URL] = findFirst[VC3_URL](c)
+func url*(c: openarray[VC3_Property]): Option[VC3_URL] = findFirst[VC3_URL](c)
 func url*(vc3: VCard3): Option[VC3_URL] = vc3.content.url
 
-func version*(c: VC3_ContentList): VC3_Version =
+func version*(c: openarray[VC3_Property]): VC3_Version =
   let found = findFirst[VC3_Version](c)
   if found.isSome: return found.get
   else: return VC3_Version(
-    contentId: c.len + 1,
+    propertyId: c.len + 1,
     group: none[string](),
     name: "VERSION",
     value: "3.0")
 func version*(vc3: VCard3): VC3_Version = vc3.content.version
 
-func class*(c: VC3_ContentList): Option[VC3_Class] = findFirst[VC3_Class](c)
+func class*(c: openarray[VC3_Property]): Option[VC3_Class] = findFirst[VC3_Class](c)
 func class*(vc3: VCard3): Option[VC3_Class] = vc3.content.class
 
-func key*(c: VC3_ContentList): seq[VC3_Key] = findAll[VC3_Key](c)
+func key*(c: openarray[VC3_Property]): seq[VC3_Key] = findAll[VC3_Key](c)
 func key*(vc3: VCard3): seq[VC3_Key] = vc3.content.key
 
-func xTypes*(c: VC3_ContentList): seq[VC3_XType] = findAll[VC3_XType](c)
+func xTypes*(c: openarray[VC3_Property]): seq[VC3_XType] = findAll[VC3_XType](c)
 func xTypes*(vc3: VCard3): seq[VC3_XType] = vc3.content.xTypes
 
 # Setters
 # =============================================================================
 
-func set*[T](vc3: var VCard3, content: varargs[T]): void =
+func set*[T: VC3_Property](vc3: VCard3, content: varargs[T]): void =
   for c in content:
     var nc = c
     let existingIdx = vc3.content.indexOfIt(it of T)
     if existingIdx < 0:
-      nc.contentId = vc3.takeContentId
+      nc.propertyId = vc3.takePropertyId
       vc3.content.add(nc)
     else:
-      nc.contentId = vc3.content[existingIdx].contentId
+      nc.propertyId = vc3.content[existingIdx].propertyId
       vc3.content[existingIdx] = nc
 
-func set*[T](vc3: VCard3, content: varargs[T]): VCard3 =
-  result = vc3
-  result.set(content)
-
-func add*[T](vc3: var VCard3, content: varargs[T]): void =
+func add*[T: VC3_Property](vc3: VCard3, content: varargs[T]): void =
   for c in content:
     var nc = c
-    nc.contentId = vc3.takeContentId
+    nc.propertyId = vc3.takePropertyId
     vc3.content.add(nc)
 
-func add*[T](vc3: VCard3, content: varargs[T]): VCard3 =
-  result = vc3
-  result.add(content)
-
-func updateOrAdd*[T](vc3: var VCard3, content: seq[T]): VCard3 =
+func updateOrAdd*[T: VC3_Property](vc3: VCard3, content: seq[T]): VCard3 =
   for c in content:
-    let existingIdx = vc3.content.indexOfIt(it.contentId == c.contentId)
+    let existingIdx = vc3.content.indexOfIt(it.propertyId == c.propertyId)
     if existingIdx < 0: vc3.content.add(c)
     else: c.content[existingIdx] = c
 
-func updateOrAdd*[T](vc3: VCard3, content: seq[T]): VCard3 =
-  result = vc3
-  for c in content:
-    let existingIdx = result.content.indexOfIt(it.contentId == c.contentId)
-    if existingIdx < 0: result.content.add(c)
-    else: c.content[existingIdx] = c
-
-# TODO: simplify with macros?
-# macro generateImmutableVersion()...
-# generateImmutableVersion("set", "add", "setName", "addSource")
-
-#[
-func setName*(vc3: var VCard3, name: string, group = none[string]()): void =
-  var name = newVC3_Name(name, group)
-  vc3.set(name)
-
-func setName*(vc3: VCard3, name: string, group = none[string]()): VCard3 =
-  result = vc3
-  result.setName(name, group)
-
-func addSource*(
-  vc3: var VCard3,
-  source: string,
-  context = none[string](),
-  setValue = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_Source(source, context, setValue, xParams, group)
-  vc3.add(c)
-
-func addSource*(
-  vc3: VCard3,
-  source: string,
-  context = none[string](),
-  setValue = false,
-  xParams: seq[VC3_XParam] = @[]): VCard3 =
-
-  result = vc3
-  result.addSource(source, context, setValue, xParams)
-
-func setFn*(
-  vc3: var VCard3,
-  fn: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_FN(fn, language, isPText, xParams, group)
-  vc3.set(c)
-
-func setFn*(
-  vc3: VCard3,
-  fn: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.setFn(fn, language, isPText, xParams, group)
-
-
-func addFn*(
-  vc3: var VCard3,
-  fn: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_FN(fn, language, isPText, xParams, group)
-  vc3.add(c)
-
-func addFn*(
-  vc3: VCard3,
-  fn: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.addFn(fn, language, isPText, xParams, group)
-
-func setN*(
-  vc3: var VCard3,
-  family: seq[string] = @[],
-  given: seq[string] = @[],
-  additional: seq[string] = @[],
-  prefixes: seq[string] = @[],
-  suffixes: seq[string] = @[],
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_N(family, given, additional, prefixes, suffixes, language,
-    isPText, xParams, group)
-  vc3.set(c)
-
-func setN*(
-  vc3: VCard3,
-  family: seq[string] = @[],
-  given: seq[string] = @[],
-  additional: seq[string] = @[],
-  prefixes: seq[string] = @[],
-  suffixes: seq[string] = @[],
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.setN(family, given, additional, prefixes, suffixes, language, isPText,
-    xParams, group)
-
-func addNickname*(
-  vc3: var VCard3,
-  nickname: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_Nickname(nickname, language, isPText, xParams, group)
-  vc3.add(c)
-
-func addNickname*(
-  vc3: VCard3,
-  nickname: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.addNickname(nickname, language, isPText, xParams, group)
-
-func addPhoto*(
-  vc3: var VCard3,
-  photo: string,
-  valueType = some("uri"),
-  binaryType = none[string](),
-  isInline = false,
-  group = none[string]()): void =
-
-  var c = newVC3_Photo(photo, valueType, binaryType, isInline, group)
-  vc3.add(c)
-
-func addPhoto*(
-  vc3: VCard3,
-  photo: string,
-  valueType = some("uri"),
-  binaryType = none[string](),
-  isInline = false,
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.addPhoto(photo, valueType, binaryType, isInline, group)
-
-func setBday*(
-  vc3: var VCard3,
-  bday: DateTime,
-  valueType = none[string](),
-  group = none[string]()): void =
-
-  var c = newVC3_Bday(bday, valueType, group)
-  vc3.set(c)
-
-func setBday*(
-  vc3: VCard3,
-  bday: DateTime,
-  valueType = none[string](),
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.setBday(bday, valueType, group)
-
-func addAdr*(
-  vc3: var VCard3,
-  adrType = @[$atIntl,$atPostal,$atParcel,$atWork],
-  poBox = "",
-  extendedAdr = "",
-  streetAdr = "",
-  locality = "",
-  region = "",
-  postalCode = "",
-  country = "",
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[]): void =
-
-  var c = newVC3_Adr(adrType, poBox, extendedAdr, streetAdr, locality, region,
-    postalCode, country, language, isPText, xParams)
-  vc3.add(c)
-
-func addAdr*(
-  vc3: VCard3,
-  adrType = @[$atIntl,$atPostal,$atParcel,$atWork],
-  poBox = "",
-  extendedAdr = "",
-  streetAdr = "",
-  locality = "",
-  region = "",
-  postalCode = "",
-  country = "",
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[]): VCard3 =
-
-  result = vc3
-  result.addAdr(adrType, poBox, extendedAdr, streetAdr, locality, region,
-    postalCode, country, language, isPText, xParams)
-
-func addLabel*(
-  vc3: var VCard3,
-  label: string,
-  adrType = @[$atIntl,$atPostal,$atParcel,$atWork],
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_Label(label, adrType, language, isPText, xParams, group)
-  vc3.add(c)
-
-func addLabel*(
-  vc3: VCard3,
-  label: string,
-  adrType = @[$atIntl,$atPostal,$atParcel,$atWork],
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.addLabel(label, adrType, language, isPText, xParams, group)
-
-func addTel*(
-  vc3: var VCard3,
-  tel: string,
-  telType = @[$ttVoice],
-  group = none[string]()): void =
-
-  var c = newVC3_Tel(tel, telType, group)
-  vc3.add(c)
-
-func addTel*(
-  vc3: VCard3,
-  tel: string,
-  telType = @[$ttVoice],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.addTel(tel, telType, group)
-
-func addEmail*(
-  vc3: var VCard3,
-  email: string,
-  emailType = @[$etInternet],
-  group = none[string]()): void =
-
-  var c = newVC3_Email(email, emailType, group)
-  vc3.add(c)
-
-func addEmail*(
-  vc3: VCard3,
-  email: string,
-  emailType = @[$etInternet],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.addEmail(email, emailType, group)
-
-func setMailer*(
-  vc3: var VCard3,
-  value: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_Mailer(value, language, isPText, xParams, group)
-  vc3.set(c)
-
-func setMailer*(
-  vc3: VCard3,
-  value: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.setMailer(value, language, isPText, xParams, group)
-
-func setTZ*(
-  vc3: var VCard3,
-  value: string,
-  isText = false,
-  group = none[string]()): void =
-
-  var c = newVC3_TZ(value, isText, group)
-  vc3.set(c)
-
-func setTZ*(
-  vc3: VCard3,
-  value: string,
-  isText = false,
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.setTZ(value, isText, group)
-
-func setGeo*(
-  vc3: var VCard3,
-  lat, long: float,
-  group = none[string]()): void =
-
-  var c = newVC3_Geo(lat, long, group)
-  vc3.set(c)
-
-func setGeo*(
-  vc3: VCard3,
-  lat, long: float,
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.setGeo(lat, long, group)
-
-func addTitle*(
-  vc3: var VCard3,
-  title: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_Title(title, language, isPText, xParams, group)
-  vc3.add(c)
-
-func addTitle*(
-  vc3: VCard3,
-  title: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.addTitle(title, language, isPText, xParams, group)
-
-func addRole*(
-  vc3: var VCard3,
-  role: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_Role(role, language, isPText, xParams, group)
-  vc3.add(c)
-
-func addRole*(
-  vc3: VCard3,
-  role: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.addRole(role, language, isPText, xParams, group)
-
-func addLogo*(
-  vc3: var VCard3,
-  logo: string,
-  valueType = some("uri"),
-  binaryType = none[string](),
-  isInline = false,
-  group = none[string]()): void =
-
-  var c = newVC3_Logo(logo, valueType, binaryType, isInline, group)
-  vc3.add(c)
-
-func addLogo*(
-  vc3: VCard3,
-  logo: string,
-  valueType = some("uri"),
-  binaryType = none[string](),
-  isInline = false,
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.addLogo(logo, valueType, binaryType, isInline, group)
-
-func setAgent*(
-  vc3: var VCard3,
-  agent: string,
-  isInline = true,
-  group = none[string]()): void =
-
-  var c = newVC3_Agent(agent, isInline, group)
-  vc3.add(c)
-
-func setAgent*(
-  vc3: VCard3,
-  agent: string,
-  isInline = true,
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.setAgent(agent, isInline, group)
-
-func setOrg*(
-  vc3: var VCard3,
-  org: seq[string],
-  isPText = false,
-  language = none[string](),
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_Org(org, isPText, language, xParams, group)
-  vc3.set(c)
-
-func setOrg*(
-  vc3: VCard3,
-  org: seq[string],
-  isPText = false,
-  language = none[string](),
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.setOrg(org, isPText, language, xParams, group)
-
-func setCategories*(
-  vc3: var VCard3,
-  categories: seq[string],
-  isPText = false,
-  language = none[string](),
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): void =
-
-  var c = newVC3_Categories(categories, isPText, language, xParams, group)
-  vc3.set(c)
-
-func setCategories*(
-  vc3: VCard3,
-  categories: seq[string],
-  isPText = false,
-  language = none[string](),
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  result = vc3
-  result.setCategories(categories, isPText, language, xParams, group)
-
-func addNote(
-  vc3: VCard3,
-  value: string,
-  language = none[string](),
-  isPText = false,
-  xParams: seq[VC3_XParam] = @[],
-  group = none[string]()): VCard3 =
-
-  var c = newVC3_Note(value, language, isPText, xParams, group)
-  vc3.add(c)
-]#
-#[
-# TODO
-note
-prodid
-rev
-sortstring
-sound
-uid
-url
-version
-class
-key
-]#
-
 # Output
 # =============================================================================
 
-func nameWithGroup(s: VC3_Content): string =
+func nameWithGroup(s: VC3_Property): string =
   if s.group.isSome: s.group.get & "." & s.name
   else: s.name
 
-func serialize(s: seq[VC3_XParam]): string =
-  result = ""
-  for x in s: result &= ";" & x.name & "=" & x.value
-
 func serialize(s: VC3_Source): string =
   result = s.nameWithGroup
   if s.valueType.isSome: result &= ";VALUE=" & s.valueType.get
@@ -1258,14 +741,14 @@ proc serialize(t: VC3_Email): string =
   if t.emailType.len > 0: result &= ";TYPE=" & t.emailType.join(",")
   result &= ":" & t.value
 
-func serialize(s: VC3_SimpleTextContent): string =
+func serialize(s: VC3_SimpleTextProperty): string =
   result = s.nameWithGroup
   if s.isPText: result &= ";VALUE=ptext"
   if s.language.isSome: result &= ";LANGUAGE=" & s.language.get
   result &= serialize(s.xParams)
   result &= ":" & s.value
 
-proc serialize(b: VC3_BinaryContent): string =
+proc serialize(b: VC3_BinaryProperty): string =
   result = b.nameWithGroup
   if b.valueType.isSome: result &= ";VALUE=" & b.valueType.get
   if b.isInline: result &= ";ENCODING=b"
@@ -1313,7 +796,7 @@ proc serialize(r: VC3_Rev): string =
 proc serialize(u: VC3_UID | VC3_URL | VC3_VERSION | VC3_Class): string =
   result = u.nameWithGroup & ":" & u.value
 
-proc serialize(c: VC3_Content): string =
+proc serialize(c: VC3_Property): string =
   if c of VC3_Name: return c.nameWithGroup & ":" & cast[VC3_Name](c).value
   elif c of VC3_Profile: return c.nameWithGroup & ":VCARD"
   elif c of VC3_Source: return serialize(cast[VC3_Source](c))
@@ -1332,10 +815,10 @@ proc serialize(c: VC3_Content): string =
   elif c of VC3_URL: return serialize(cast[VC3_URL](c))
   elif c of VC3_Version: return serialize(cast[VC3_Version](c))
   elif c of VC3_Class: return serialize(cast[VC3_Class](c))
-  elif c of VC3_SimpleTextContent:
-    return serialize(cast[VC3_SimpleTextContent](c))
-  elif c of VC3_BinaryContent:
-    return serialize(cast[VC3_BinaryContent](c))
+  elif c of VC3_SimpleTextProperty:
+    return serialize(cast[VC3_SimpleTextProperty](c))
+  elif c of VC3_BinaryProperty:
+    return serialize(cast[VC3_BinaryProperty](c))
 
 proc `$`*(vc3: VCard3): string =
   result = "BEGIN:VCARD" & CRLF
@@ -1347,41 +830,8 @@ proc `$`*(vc3: VCard3): string =
 
 # Parsing
 # =============================================================================
-import vcard/private/parsercommon
 
-type
-  VC3Parser = object of VCardLexer
-    filename: string
-
-  VC3Param = object
-    name*: string
-    values*: seq[string]
-    isPText*: bool
-
-  VCard3ParsingError = object of ValueError
-
-const NON_ASCII = { '\x80'..'\xFF' }
-const SAFE_CHARS = WSP + { '\x21', '\x23'..'\x2B', '\x2D'..'\x39', '\x3C'..'\x7E' } + NON_ASCII
-const QSAFE_CHARS = WSP + { '\x21', '\x23'..'\x7E' } + NON_ASCII
-const VALUE_CHAR = WSP + { '\x21'..'\x7E' } + NON_ASCII
-
-proc error(p: VC3Parser, msg: string) =
-  raise newException(VCard3ParsingError, "$1($2, $3) Error: $4] " %
-    [ p.filename, $p.lineNumber, $p.getColNumber(p.pos), msg ])
-
-proc readName(p: var VC3Parser): string =
-  ## Read a name from the current read position or error. As both content types
-  ## and paramaters use the same definition for valid names, this method is
-  ## used to read in both.
-  p.setBookmark
-  let validChars = ALPHA_NUM + {'-'}
-  while validChars.contains(p.peek): discard p.read
-  result = p.readSinceBookmark.toUpper()
-  if result.len == 0:
-    p.error("expected to read a name but found '$1'" % [$p.peek])
-  p.unsetBookmark
-
-proc readParamValue(p: var VC3Parser): string =
+proc readParamValue(p: var VCardParser): string =
   ## Read a single parameter value at the current read position or error.
   p.setBookmark
   if p.peek == '"':
@@ -1399,12 +849,12 @@ proc readParamValue(p: var VC3Parser): string =
   if result.len == 0:
     p.error("expected to read a parameter value")
 
-proc readParams(p: var VC3Parser): seq[VC3Param] =
+proc readParams(p: var VCardParser): seq[VC_Param] =
   ## Read all parameters for the current content line at the current read head.
   result = @[]
   while p.peek == ';':
     discard p.read
-    var param = VC3Param(name: p.readName, values: @[])
+    var param: VCParam = (p.readName, @[])
     p.expect("=", true)
     param.values.add(p.readParamValue)
     while p.peek == ',':
@@ -1412,14 +862,15 @@ proc readParams(p: var VC3Parser): seq[VC3Param] =
       param.values.add(p.readParamValue)
     result.add(param)
 
-proc readValue(p: var VC3Parser): string =
-  ## Read a content value at the current read position.
-  p.setBookmark
-  while VALUE_CHAR.contains(p.peek): discard p.read
-  result = p.readSinceBookmark
-  p.unsetBookmark
+proc getXParams(params: openarray[VCParam]): seq[VC_XParam] =
+  ## Filter out and return only the non-standard parameters starting with "x-"
 
-proc readTextValue(p: var VC3Parser, ignorePrefix: set[char] = {}): string =
+  let ps = params.toSeq
+  return ps -->
+    filter(it.name.startsWith("x-")).
+    map((name: it.name, value: it.values.join(",")))
+
+proc readTextValue(p: var VCardParser, ignorePrefix: set[char] = {}): string =
   ## Read a text-value (defined by RFC2426) from the current read position.
   ## text-value is a more constrained definition of possible value characters
   ## used in content types like N and ADR.
@@ -1442,12 +893,12 @@ proc readTextValue(p: var VC3Parser, ignorePrefix: set[char] = {}): string =
     else: result.add(c)
 
 proc readTextValueList(
-    p: var VC3Parser,
+    p: var VCardParser,
     seps: set[char] = {','},
     ifPrefix = none[char]()
   ): seq[string] =
   ## Read in a list of multiple text-value (defined by RFC2426) values from the
-  ## current read position. This is used, for example, but the N content type.
+  ## current read position. This is used, for example, by the N content type.
 
   if ifPrefix.isSome:
     if p.peek != ifPrefix.get: return @[]
@@ -1456,116 +907,7 @@ proc readTextValueList(
   result = @[p.readTextValue]
   while seps.contains(p.peek): result.add(p.readTextValue(ignorePrefix = seps))
 
-proc skip(p: var VC3Parser, expected: string, caseSensitive = false): bool =
-  p.setBookmark
-  if caseSensitive:
-    for ch in expected:
-      if p.read != ch:
-        p.returnToBookmark
-        return false
-
-  else:
-    for rune in expected.runes:
-      if p.readRune.toLower != rune.toLower:
-        p.returnToBookmark
-        return false
-
-  p.unsetBookmark
-  return true
-
-proc existsWithValue(
-    params: openarray[VC3Param],
-    name, value: string,
-    caseSensitive = false
-  ): bool =
-
-  ## Determine if the given parameter exists and has the expected value. By
-  ## default, value checks are not case-sensitive, as most VCard values are not
-  ## defined as being case-sensitive.
-
-  let ps = params.toSeq
-
-  if caseSensitive:
-    ps --> exists(
-      it.name == name and
-      it.values.len == 1 and
-      it.values[0] == value)
-  else:
-    ps --> exists(
-      it.name == name and
-      it.values.len == 1 and
-      it.values[0].toLower == value.toLower)
-
-proc getMultipleValues(
-    params: openarray[VC3Param],
-    name: string
-  ): seq[string] =
-
-  ## Get all of the values for a given parameter in a single list. There are
-  ## two patterns for multi-valued parameters defined in the VCard RFCs:
-  ##
-  ##   - TYPE=work,cell,voice
-  ##   - TYPE=work;TYPE=cell;TYPE=voice
-  ##
-  ## Parameter values can often be specific using both patterns. This method
-  ## joins all defined values regardless of the pattern used to define them.
-
-  let ps = params.toSeq
-  ps -->
-    filter(it.name == name).
-    map(it.values).
-    flatten()
-
-proc getSingleValue(params: openarray[VC3Param], name: string): Option[string] =
-  ## Get the first single value defined for a parameter.
-  #
-  # Many parameters only support a single value, depending on the content type.
-  # In order to support multi-valued parameters our implementation stores all
-  # parameters as seq[string]. This function is a convenience around that.
-
-  let ps = params.toSeq
-  let foundParam = ps --> find(it.name == name)
-
-  if foundParam.isSome and foundParam.get.values.len > 0:
-    return some(foundParam.get.values[0])
-  else:
-    return none[string]()
-
-proc validateNoParameters(
-    p: VC3Parser,
-    params: openarray[VC3Param],
-    name: string
-  ) =
-
-  ## Error unless there are no defined parameters
-  if params.len > 0:
-    p.error("no parameters allowed on the $1 content type" % [name])
-
-proc validateRequiredParameters(
-    p: VC3Parser,
-    params: openarray[VC3Param],
-    expectations: openarray[tuple[name: string, value: string]]
-  ) =
-
-  ## Some content types have specific allowed parameters. For example, the
-  ## SOURCE content type requires that the VALUE parameter be set to "uri" if
-  ## it is present. This will error if given parameters are present with
-  ## different values that expected.
-
-  for (n, v) in expectations:
-    let pv = params.getSingleValue(n)
-    if pv.isSome and pv.get != v:
-      p.error("parameter '$1' must have the value '$2'" % [n, v])
-
-proc getXParams(params: openarray[VC3Param]): seq[VC3_XParam] =
-  ## Filter out and return only the non-standard parameters starting with "x-"
-
-  let ps = params.toSeq
-  return ps -->
-    filter(it.name.startsWith("x-")).
-    map((name: it.name, value: it.values.join(",")))
-
-proc parseContentLines(p: var VC3Parser): seq[VC3_Content] =
+proc parseContentLines*(p: var VCardParser): seq[VC3_Property] =
   result = @[]
 
   macro assignCommon(assign: untyped): untyped =
@@ -1593,7 +935,7 @@ proc parseContentLines(p: var VC3Parser): seq[VC3_Content] =
     let group = p.readGroup
     let name = p.readName
     if name == "END":
-      p.expect(":VCARD\r\n")
+      p.expect(":VCARD" & CRLF)
       break
     let params = p.readParams
     p.expect(":")
@@ -1609,7 +951,7 @@ proc parseContentLines(p: var VC3Parser): seq[VC3_Content] =
         p.error("the value of the PROFILE content type must be \"$1\"" %
           ["vcard"])
       p.validateNoParameters(params, "NAME")
-      result.add(VC3_Content(group: group, name: name))
+      result.add(VC3_Property(group: group, name: name))
 
     of $cnSource:
       p.validateRequiredParameters(params,
@@ -1829,26 +1171,6 @@ proc parseContentLines(p: var VC3Parser): seq[VC3_Content] =
 
     p.expect("\r\n")
 
-proc parseVCard3*(input: Stream, filename = "input"): seq[VCard3] =
-  var p: VC3Parser
-  p.filename = filename
-  lexer.open(p, input)
-
-  while p.peek != '\0': # until EOF?
-    var vcard = VCard3()
-    discard p.readGroup
-    p.expect("begin:vcard")
-    while (p.skip("\r\n", true)): discard
-    for content in p.parseContentLines: vcard.add(content)
-    while (p.skip("\r\n", true)): discard
-    result.add(vcard)
-
-proc parseVCard3*(content: string, filename = "input"): seq[VCard3] =
-  parseVCard3(newStringStream(content), filename)
-
-proc parseVCard3File*(filepath: string): seq[VCard3] =
-  parseVCard3(newFileStream(filepath, fmRead), filepath)
-
 #[
 Simplified Parsing Diagram
 
@@ -1881,15 +1203,14 @@ stateDiagram-v2
 
 ## Private Function Unit Tests
 ## ============================================================================
-proc runVcard3PrivateTests*() =
+proc runVCard3PrivateTests*() =
 
-  proc initParser(input: string): VC3Parser =
-    result = VC3Parser(filename: "private unittests")
+  proc initParser(input: string): VCardParser =
+    result = VCardParser(filename: "private unittests")
     lexer.open(result, newStringStream(input))
 
-  # "vcard/vcard3/private"
+  # "readGroup":
   block:
-
     var p = initParser("mygroup.BEGIN:VCARD")
     let g = p.readGroup
     assert g.isSome
@@ -2032,4 +1353,4 @@ proc runVcard3PrivateTests*() =
       assert "" == "validateRequiredParameters should have errored"
     except CatchableError: discard
 
-when isMainModule: runVcard3PrivateTests()
+when isMainModule: runVCard3PrivateTests()
diff --git a/tests/tvcard3.nim b/tests/tvcard3.nim
index 1e1f294..7e9a1f5 100644
--- a/tests/tvcard3.nim
+++ b/tests/tvcard3.nim
@@ -1,6 +1,7 @@
 import options, unittest, zero_functional
 
 import ./vcard
+import ./vcard/vcard3
 
 suite "vcard/vcard3":
 
@@ -8,7 +9,8 @@ suite "vcard/vcard3":
     runVcard3PrivateTests()
 
   let jdbVCard = readFile("tests/jdb.vcf")
-  let jdb = parseVCard3(jdbVCard)[0]
+  # TODO: remove cast after finishing VCard4 implementation
+  let jdb = cast[VCard3](parseVCards(jdbVCard)[0])
 
   test "parseVCard3":
     check:
@@ -17,7 +19,7 @@ suite "vcard/vcard3":
       jdb.fn.value == "Jonathan Bernard"
 
   test "parseVCard3File":
-    let jdb = parseVCard3File("tests/jdb.vcf")[0]
+    let jdb = cast[VCard3](parseVCardsFromFile("tests/jdb.vcf")[0])
     check:
       jdb.email.len == 7
       jdb.email[0].value == "jonathan@jdbernard.com"
@@ -70,9 +72,9 @@ suite "vcard/vcard3":
       "EMAIL;TYPE=INTERNET:howes@netscape.com\r\n" &
       "END:vCard\r\n"
 
-    let vcards = parseVCard3(vcardsStr)
+    let vcards = parseVCards(vcardsStr)
     check:
       vcards.len == 2
-      vcards[0].fn.value == "Frank Dawson"
-      vcards[0].email.len == 2
-      (vcards[0].email --> find(it.emailType.contains("PREF"))).isSome
+      cast[VCard3](vcards[0]).fn.value == "Frank Dawson"
+      cast[VCard3](vcards[0]).email.len == 2
+      (cast[VCard3](vcards[0]).email --> find(it.emailType.contains("PREF"))).isSome