purpose

A rulesheet repository is a secured management system for CDCL rulesheets that employs version control. See some rulesheet examples. A rulesheet repository does not necessarily offer features for rulesheet editing, but it may. The secured management system is one that requires authenticated client access to rulesheets, with the exception of the rulesheet retrieval use-case, where authentication is optional. In all cases, its client connections are strongly secured, and all known client authorizations are honored/enforced.

Version control is comprised of: Also see this page's sections on rulesheet management and author management.


Adding rulesheets

The rulesheet author represents a stakeholder. Upon checking in a rulesheet, the author must define these attributes for the rulesheet:

  1. the stakeholder entity; which is one selected option from an authorized list of options offered to the authoring user. The authorized list is one that is kept synchronized (as best as can be afforded) once the authoring user is given authenticated access to the repository (for more on this, see Author Management). The authorized list must be comprised of options where each option has a valid stakeholder URI found in a stakeholder directory. The Stakeholder Directories are the authoritative sources of these authorizations.
  2. publishing period start; the date and time on which the rulesheet is considered first available as a published rulesheet. The date and time are defaulted to the present moment at the time of check-in, but the user may post-date these. It is not permissible to pre-date them.
  3. publishing period end; the date and time on which the rulesheet is considered no longer available as a published rulesheet (to "auto-retire"). This may be left undefined, which is to be interpreted as an indefinite publishing period; however, the author must positively acknowledge leaving this attribute undefined.
  4. draft status, which may be defaulted to true; any rulesheet with a draft status of true is considered not published for production consumption
  5. utility status (defaults to false), which when true, means that the rulesheet is not subject to uniqueness constraints (see below) on problem space and Primary Custodian, both of which must be null for a utility rulesheet. The objective is that a utility rulesheet is only ever included by other rulesheets and cannot serve as a rulesheet on its own. Therefore: a utility rulesheet is not accessible through Rulesheet Retrieval's typical use-case of a consuming Gatepoint acting as requesting party; a utility rulesheet is accessible only via include directives within other rulesheets or via Rulesheet Retrieval when an auditor is the requesting party, which is a special case of Rulesheet Retrieval (see below).
See a discussion about collation, which covers the importance of associating rulesheets to problem spaces and/or to primary custodians.

The rulesheet author may optionally define these attributes for the rulesheet:

  1. comments relating to the checked-in rulesheet.
  2. one or more Problem Spaces against which this rulesheet may be applied; any rulesheets with this attribute defined are considered exceptional policies that override the sole general policy in effect for the same publishing date
  3. one or more primary custodians (entities other than the author's defined stakeholder) of documents against which this rulesheet may be applied; any rulesheets with this attribute defined are considered exceptional policies that override the sole general policy in effect for the same publishing date
  4. rulesheet filename, except this attribute is mandatory when the rulesheet's utility status is true
Note that if an author does not choose to define either document types or primary custodians, then that rulesheet will be used as the sole general policy in this repository for the author's represented stakeholder within the defined publishing period.

Primary custodianship is intrinsic to the document under redaction; it is explicitly defined and embedded within the document under redaction. In other words, no one can claim primary custodianship outside the realm of the run-time document instance and certainly cannot usurp it through any mechanism within a rulesheet.

For utility rulesheets, the repository will enforce uniqueness of rulesheets by the following "keys":

For non-utility rulesheets, the repository will enforce uniqueness of rulesheets by the following "keys": The repository will also enforce uniqueness of non-utility rulesheets in non-draft status and irrespective of version number by: Explanation: The objective is that a stakeholder's non-draft rulesheets applied to the same problem space and/or primary custodian may not have overlapping publishing periods. Hence, it is a violation to have multiple non-draft rulesheets defined for the same stakeholder, date-time, & primary custodian or for the same stakeholder, date-time, & problem space.

Rulesheet URL and other metadata when rulesheet is saved

Since it is possible that two separate, exceptional rulesheets, one for the requested problem space and another for the requested primary custodian, may be discovered during a rulesheet retrieval operation, the repository shall inform the author of its implemented conflict resolution during rulesheet addition and change operations (for more about conflict resolution, see Rulesheet Retrieval).

The repository, upon check-in, must conduct a syntax check validation of the rulesheet. Rulesheets are either confirmed by or assumed by the repository to be in any supported authoring form. If the validation fails, a report is provided in the response to the author, and the rulesheet version is marked by the repository as unusable. If on the other hand the validation succeeds, the success status is provided in the response to the author, and the rulesheet is marked by the repository as usable.

If the rulesheet is in non-draft status and is marked as unusable, the author is prompted to either abandon the save request or force a save of the change to the repository. The author is informed through this same prompt that a forced save of an unusable rulesheet in non-draft status will likely result in no available enforceable policy for this particular rulesheet "key".

The repository assigns a URL to the checked-in rulesheet and incorporates any rulesheet "filename" that the author may supply at author's option, and it assigns a sequential version number (integer) within the scope of the URL for purposes of tracking revisions/changes. The first version number must be one (1). If the URL already exists, the check-in shall fail with a prompt to the author to choose a different "filename". The date-time stamp of the moment of check-in is automatically calculated and must be included in the metadata for the checked-in version of the rulesheet for purposes of resolving contention resulting from concurrent actions by multiple authors. The identity of the rulesheet author committing the save is also included in the metadata.

To resolve contention over a rulesheet when multiple parties attempt changes, validations, and/or retirement, only the first action is honored, and that action causes the last update timestamp of the rulesheet to be refreshed. This causes the reported last update timestamps from all subsequent contentious requests to be out of date, essentially invalidating contention before it starts.


Changing rulesheets

Any author with the authority to represent a stakeholder may change the latest version of any rulesheet affiliated with that stakeholder. Versions that have been superseded are not modifiable and are excluded from author selection for change; authors may, however, retrieve read-only views of superseded versions. Effectively, a rulesheet change - when successfully saved - creates a new rulesheet object with a new version number, except when the changes are limited only:

...in which case a new rulesheet object is not created. The effect of this is that change history is tracked through the lineage of versions, but (1) modifying a rulesheet from draft to non-draft and (2) changes to comments within a single version and (3) rulesheet retirement - when these are accomplished without any other changes - are not tracked by new rulesheet versions.

Publishing period start is read-only when it is in the past, with the following exception. Both publishing period start and publishing period end must be modified when the rulesheet being changed is already retired (i.e. the publishing period end is in the past); the date-times in this case shall be subject to the same business rules as for adding rulesheets (see above). Note that publishing period start is permitted on a rulesheet change to be in the past only when the rulesheet being changed was not retired, unlike when adding a rulesheet; in other words, since it's read-only in this case, it's not subject to validation.

The following are read-only for rulesheet changes:

  1. the stakeholder entity
  2. rulesheet filename
Rules apply when saving the rulesheet. Rulesheet uniqueness is enforced as it is when Adding Rulesheets. The repository increments the version number, a URL is generated (see above), and the last update timestamp of the rulesheet is refreshed. If the rulesheet's draft status is saved as false, then the prior version of this rulesheet with draft status of false that overlaps the publishing period (if any such rulesheet exists) is retired by setting its publishing period end to the current date-time. Rulesheets with superseded version numbers retain their URLs for potential audit purposes and certainly for production purposes in potential cases where there is a rulesheet with draft status of false for which all superseding versions have draft status of true.

If the author attempts to save any changes made to either Problem Space or Primary Custodian, the repository shall first inform the author as to the fundamental change for the stakeholder's policy that doing so implies.


Duplicating rulesheets

Any author with the authority to represent a stakeholder may duplicate any rulesheet affiliated with that stakeholder. Duplication is essentially a convenience use-case for the efficient addition of a new rulesheet. An existing rulesheet's attributes may be used to "guide" data entry of the fields in a variation of the Adding Rulesheets use-case, and this is called duplicating the rulesheet. The objective is to facilitate creation of a new rulesheet that may share much rulesheet content in common with an existing rulesheet: to avoid much redundant rule definition.

Behavior of fields:

  1. the stakeholder entity field is prepopulated with the value of the "origin" rulesheet, and the author may change this value
  2. publishing period start is defaulted to the present moment at the time of check-in, but the value of the "origin" rulesheet is displayed separately for the user's reference. The user may post-date these. It is not permissible to pre-date them.
  3. publishing period end is defaulted to null, but the value of the "origin" rulesheet is displayed separately for the user's reference. This may be left undefined. However, the author must positively acknowledge leaving this attribute undefined.
  4. draft status is prepopulated with the value of the "origin" rulesheet, and the author may change this value
  5. comments is prepopulated with the value of the "origin" rulesheet, and the author may change this value
  6. Problem Space is defaulted to null, but the value of the "origin" rulesheet is displayed separately for the user's reference and potential copying/pasting purposes
  7. primary custodian is defaulted to null, but the value of the "origin" rulesheet is displayed separately for the user's reference and potential copying/pasting purposes
  8. rulesheet filename is defaulted to null, but the value of the "origin" rulesheet is displayed separately for the user's reference
This use-case proceeds identically to that for Adding Rulesheets.


Validating rulesheets

Any author with the authority to represent a stakeholder may validate any rulesheet affiliated with that stakeholder. In addition, a repository may automatically (or at administrative option) validate any rulesheet, especially when syntax validation rules are updated.

When the usable/unusable status changes, the last update timestamp of the rulesheet is refreshed. The identity of the entity triggering the validation is also included. It is not refreshed at the conclusion of validation when the status is left unchanged, since there is no change to persist.

Rules apply as when saving the rulesheet, except the end result typically involves no change to the persisted rulesheet unless the usable/unusable status must be updated to correspond to the success or failure, respectively, of the validation.


Retiring rulesheets (including auto-retirement)

Any author with the authority to represent a stakeholder may retire any rulesheet affiliated with that stakeholder. Rulesheets also automatically retire (auto-retire) when the end of the publishing period passes. When an author elects to retire a rulesheet, the rulesheet's publishing period end date-time is automatically assigned the value of the current time, thus effecting an "auto-retire". This may be called a "forced aging" of the publishing period end. Retired rulesheets retain their URLs for potential audit purposes.

When a rulesheet retires via a change in the publishing period end, the last update timestamp of the rulesheet is refreshed. The identity of the entity triggering the retirement is also included.

Rules apply as when saving the rulesheet.

Note that individual versions of rulesheets are never taken out of retirement. Retirement is a permanent change in rulesheet state for a specific version. For further information, see the section about Changing Rulesheets.


Rulesheet retrieval

The typical client of this use-case is a Gatepoint. However, this use-case can be employed by an auditor.

Logical consistency checking (a part of Validating Rulesheets) is limited in scope to a rulesheet and its included rulesheets. Therefore, in exceeding this scope with a group of independent rulesheets (which represent multiple disclosure policies), logical consistency across the group cannot be assured to be coherent when the rulesheets are taken together. A single stakeholder is assumed to desire logical consistency throughout its own policies WHEN THEY ARE APPLIED. Certainly, a stakeholder may have to define inconsistent policies, but it is assumed that such inconsistencies would never be applicable to a given disclosure problem. (It is not expected, of course, that logical consistency span across the policies of multiple stakeholders.) This is why CDCL requires no more than one rulesheet per stakeholder to be added to an assembled rulesheet deck (i.e. for a given problem space).

Since it is possible that two separate rulesheets, one for the requested problem space and another for the requested stakeholder, may be discovered as exceptional policies (see Adding Rulesheets) during a rulesheet retrieval operation, the repository must implement a single, predictive conflict resolution scheme. The repository informs the authors (see Saving Rulesheets) of this scheme, and authors are assumed to have an understanding of it. The scheme is:

If a rulesheet is not identified by both Problem Space and Primary Custodian, then a rulesheet found by Primary Custodian alone takes precedence over a rulesheet found by Problem Space alone. If no rulesheet is found via this scheme, then the generic policy rulesheet (where the rulesheet's Primary Custodian metadata is null and its Problem Space metadata is null) is applied, if found.
policy type associated Primary Custodianassociated Problem Space
overrides rows belowexceptional "custodians' exchanges" one or more definedone or more defined
overrides rows belowexceptional custodians one or more definednone defined
overrides row belowexceptional exchanges none definedone or more defined
is overridden by rows abovegeneric none definednone defined
For input arguments of (Gatepoint's supported authoring forms/versions, entity's stake {Primary Custodian or Stakeholder}, Problem Space, entity URI, & Primary Custodian URI), the repository will provide as a result a single rulesheet under these criteria:
  1. the rulesheet to be returned has an authoring form language version supported by the calling Gatepoint
  2. the entity URI matches the returned rulesheet's stakeholder entity
  3. the Problem Space matches one member of the returned rulesheet's problem spaces or, if there is no such matching rulesheet, the rulesheet with null problem spaces
  4. the Primary Custodian URI matches one member of the returned rulesheet's primary custodians or, if there is no such matching rulesheet, the rulesheet with null primary custodians; note that when the entity URI equals the Primary Custodian URI, there will likely be no rulesheets found with non-null primary custodians to satisfy this search criterion; instead, the general policy will likely be the rulesheet to return
  5. where all internal "includes" are resolved (the repository will accomplish this so that all rulesheet logic is in scope in the single output rulesheet)
  6. the returned rulesheet has a publishing period encompassing the present moment
  7. the returned rulesheet has a mark of usable (previously resulting from a successful syntax check)
  8. the returned rulesheet is not a draft
  9. the returned rulesheet is not a utility rulesheet
  10. the returned rulesheet is not retired. this ought to be redundant with the publishing period criterion above as long as retirement is implemented by "forced aging" of the publishing period end
If there are multiple versions of this rulesheet that satisfy these criteria, only the latest version is returned. If one or more criteria are not met, including failure to resolve all "includes", then the repository will respond with a "not-found" status and log the failure event for review by the administrators of the Rulesheet Repository and by the authorized authors of the stakeholder entity.

There are special cases of rulesheet retrieval:

  1. One special case is permitted to auditors and authors. This special case either extends the case above by the auditor's or author's inclusion of the input argument of date-time or instead retrieves a rulesheet when given an input argument of a rulesheet URL. This special case also ignores usable status and ignores utility status. When a date-time is provided as an input argument, all rulesheet versions (there may be multiple) that satisfy the remaining criteria and have a publishing period encompassing the date-time input argument (essentially ignoring retired status) shall be returned. When a rulesheet URL is provided as an input argument, then either that rulesheet is faithfully returned or a "not found" error response is faithfully returned. Rulesheets to be returned are returned without internal includes resolved.
  2. A second special case is permitted to other rulesheet repositories. This special case is one that is very straightforward and is intended to resolve a certain variety of include directives that may exist within rulesheets. The risk of circumventing stakeholder legitimacy within Stakeholder Directories is too high. So, in response to an author's question of "How do I include my parent company's policy in my own?", the answer is "You must either convince the Stakeholder Directories to involve your parent company as a stakeholder or get a copy of your parent company's policy and save it as your own".


Rulesheet management

This use-case is the means by which an author may locate an existing rulesheet for the purpose of changing, duplicating, validating, or retiring it.

The author's user context shall include a list of authorizing stakeholders. When the author selects one stakeholder from this list, the list of all existing, checked-in rulesheets for that stakeholder are displayed, irrespective of version. This means that if a rulesheet exists as versions 1 and 2, only one entry in the displayed list is shown.

The authorized list is one that is kept synchronized (as best as can be afforded) once the authoring user is given authenticated access to the repository. The authorized list must be comprised of options where each option has a valid stakeholder URI found in a stakeholder directory. The Stakeholder Directories are the authoritative sources of these authorizations.

When the author selects a rulesheet from the list for any of changing, duplicating, validating, or retiring, that rulesheet is applied to the use-case that the author chose as long as there is only one version of that rulesheet in existence. If there are multiple versions in existence, then an intermediary list of all existing versions is shown for the author. All versions are available for the author to retrieve and view (see rulesheet retrieval special case below). The latest version with a draft status of false is the only version available for the author to select for the intended use-case (changing, duplicating, validating, or retiring).


Author management

A rulesheet repository may implement its own validation/vetting/authorization rules to be met before an individual is given account access to the repository. However, the repository must expose a receiving interface for messages from Stakeholder Directories concerning stakeholders' authorizations of rulesheet authors. These authorizations will be used as described above for creating the list of stakeholder entities when adding rulesheets.

Author URIs found to be invalid within the scope of this rulesheet repository must be ignored. A message subsequent to an earlier message shall overwrite expiration date-time only when the identical author URI is contained in that subsequent message. Independent of the arrival of messages on this interface, the expiration date-times must be honored. The message content of Stakeholder Directory URI must be authorized to the specific Stakeholder Directory that sent the message, and the manner in which this authorization is done is up to the rulesheet repository implementation.

Upon giving account access to the repository, the repository must be prepared to cache the authorizations sent by Stakeholder Directories, especially when the author is not engaged in a session (i.e. off line). Therefore, some identifier within the scope of the repository must be created to uniquely identify the author when either on line or off line. This identifier must not be the author's authenticating userID (i.e. not the log-in ID). The composite of the author's identifier, an @ sign, and the rulesheet repository URI shall be the author URI, and this author URI shall be divulged by the rulesheet repository to the author. The author is then permitted to share knowledge of the author URI with any Stakeholder Directories and with any stakeholders for the purposes of potential authorizations. A hypothetical example of an author URI looks like:
H67601@http://my.business.net/rulesheetrepository/