--- a/doc/tags-and-attributes.txt	Sat Mar 29 22:37:18 2008 -0700
+++ b/doc/tags-and-attributes.txt	Mon Mar 31 13:53:12 2008 -0700
@@ -1,37 +1,143 @@
 
-pkg
+PSARC/2008/190
+pkg(5): image packaging system
+
 TAGS AND ATTRIBUTES
 
 1.  Definitions
 
-    Tags are the settings that affect individual files within a package.
-    Tags may eventually have values, depending on how many tags are
-    required to handle the SPARC-based platform binaries.
+    Both packages and actions within a package can carry metadata, which
+    we informally refer to as attributes and tags.
 
     Attributes:  settings that apply to an entire package.  Introduction
     of an attribute that causes different deliveries by the client could
     cause a conflict with the versioning algebra, so we attempt to avoid
     them.
 
-2.  Tags
+    Tags are the settings that affect individual files within a package.
+    Tags may eventually have values, depending on how many tags are
+    required to handle the SPARC-based platform binaries.
+
+2.  Attribute and tag syntax and namespace
+
+2.1.  Syntax
+
+    The syntax for attributes and tags is similar to that used for
+    pkg(5) and smf(5) FMRIs.
+
+    [org_prefix,][name][:locale]
 
-platform
+    The organizational prefix is a forward-ordered or reverse-ordered
+    domain name, followed by a common.  The name field is a  
+    The default locale, if the locale field is omitted is "C", a 7-bit
+    ASCII locale.
+
+    Each of these fields is [A-Za-z][A-Za-z0-9_-.]*.
+
+2.2.  Unprefixed attributes and tags.
+
+    All unprefixed attributes and tags are reserved for use by the
+    framework.
+
+    Generally, unprefixed tags are introduced in the definition of an
+    action.
+
+2.3.  Attributes and tags common to all packages
 
-ISA (particularly need to know i386 on i86pc vs amd64 on i86pc)
+    The "pkg" attribute is to be used for attributes common to all
+    packages, regardless of which particular OS platforms that a specific
+    package may target.
+
+2.3.1.  Common attributes
+
+    pkg.name
+       A short, descriptive name for the package.  In accordance with
+       2.1 above, pkg.name:fr would be the descriptive name in French.
+       Exact numerical version strings are discouraged in the
+       descriptive name.
+
+       Example:  "Apache HTTPD Web Server 2.x"
+
+    pkg.description
+       A descriptive paragraph for the package.  Exact numerical version
+       strings can be embedded in the paragraph.
 
-debug/non-debug
+    pkg.detailed_url
+       One or more URLs to pages or sites with further information about
+       the package.
+
+2.3.2.  Common tags
 
-compatibility
+    pkg.debug
+       This file is used when the package is intended to be installed in
+       a debug configuration.  For example, we expect to deliver a debug
+       version of the kernel, in addition to the standard non-debug
+       version.
+
+    XXX pkg.platform
+
+    XXX ISA (particularly need to know i386 on i86pc vs amd64 on i86pc)
+
+    pkg.compatibility
 	(for shipping non-bleeding edge .so.x.y.z copies, perhaps)
 
+2.4.  Attributes common to all packages for an OS platform
 
-3.  Attributes
+    Each OS platform is expected to define a string representing that
+    platform.  For example, the OpenSolaris platform is represented by
+    the string "opensolaris".
+
+    XXX Or "osol"?
+
+2.4.1.  OpenSolaris attributes
+
+    opensolaris.arc_url
+        One or more URLs associated with the ARC case or cases
+	associated with the component(s) delivered by the package.
+
+    opensolaris.maintainer
+        A human readable string describing the entity providing the
+	package.  For an individual, this string is expected to be their
+	name, or name and email.
+
+    opensolaris.maintainer_url
+        A URL associated with the entity providing the package.
+
+    opensolaris.upstream
+	A human readable string describing the entity that creates the
+	software.  For an individual, this string is expected to be
+	their name, or name and email.
 
-3.1.  Useful attributes
+    opensolaris.upstream_url
+        A URL associated with the entity that creates the 
+	software delivered within the package.
+
+    opensolaris.source_url
+        A URL to the source code bundle, if appropriate, for the package.
+
+    opensolaris.repository_url
+        A URL to the source code repository, if appropriate, for the
+	package.
+
+    opensolaris.repository_changeset
+        A changeset ID for the version of the source code contained in
+	opensolaris.repository_url.
 
-    Package aliases?
+    opensolaris.gui.classification
+        A list of labels classifying the package into the categories
+	shared among pkg(5) graphical clients.
+
+2.5.  Organization specific attributes
 
-3.2.  Attributes best avoided
+    Organizations wishing to provide a package with additional metadata
+    or to amend an existing package's metadata (in a repository that
+    they have control over) must use an organization-specific prefix.
+    For example, a service organization might introduce
+    "service.example.com,support_level" or
+    "com.example.service,support_level" to describe a level of support
+    for a package and its contents.
+
+3.3.  Attributes best avoided
 
 built-on release
 
@@ -73,3 +179,5 @@
     simple approach would be to base it on base/minimal's release,
     rather than uname(1) output.
 
+
+