Claims Adjudicator Module

Installation

npm i @byu-oit/ts-claims-engine

Introduction

The Claim Adjudicator Module (CAM, aka the Claims Engine) provides a facet of the
domain contract through which other domains may verify information without having
to obtain a copy of that information. For example, in order to determine whether
a person is older than 21, many systems store that person's birth date. The CAM
enables domains to store the binary answer to the questions, "Is this person older
than 21?", instead of the more problematic date of birth.

$3

* Claim - A subject identifier and one or more tuples defining the relationship of the value of a concept associated with the subject and a reference value
* Concept - A domain-specific value or state about which a claim may be validated. A concept can be anything from a single internal data element to the result of a complex internal process. That is, concepts can be more abstract than the properties associated with a domain's resources and subresources.
* Mode - A verb that modifies the behavior of the claim engine. Modes include ALL (the default), which requires all claims in the claim array to be true to verify the claim, and ONE, which requires only one of the claims in the claim array to be true to verify the claim.
* Qualifier - An optional object containing domain-specific properties that is passed to the concept resolution code to further qualify the claim.
* Relationship - The claimed relationship between the value of the concept for the specified subject and the reference value. Relationships include "match," "gt_or_eq-to," and "lt_or_eq-to."
* Subject - A domain-specific resource identifier.

$3

More formally, the CAM determines whether a claimed relationship between the value
of the instance of a concept and a reference value can be verified.

One or more claims may be made in the context of a subject. A claim expression is
comprised of a subject identifier, a mode, and an array of claim tuples:

{
"subject": "123456789",
"mode": "ALL",
"claims": [
]
}

The claim, "this person is older than 21," is expressed as a typed tuple:

{
"concept": "age",
"relationship": "gt_or_eq",
"value": "21"
}

The CAM operates on domain-specific concepts. A concept may be anything from a
the value of a specific column in a row identified by the subject ID to a value
dynamically determined by a function.

In the older-than-21 example, the domain might subtract the birth date of the
subject from the current date to derive an age to compare with the reference value.

#### Qualifier

The claim tuple in the example above omitted the optional qualifier property.
A qualifier is an object with domain-specific properties. It is passed, along with
the subject ID to the concept resolution code to further qualify the claim.

{
"concept": "age",
"relationship": "gt_or_eq",
"value": "21",
"qualifier": { ageMonthOffset: 5 }
}

In this example, the ageMonthOffset qualifier asks if the person will be older
than 21 in 5 months.

API

Some of the parameters and return types are complex objects. Instead of defining them in the method definitions, they have been defined in the types file. Some of the more important types are defined in the Appendix under API Reference.

$3

Creates a new instance of the ClaimsAdjudicator
``ts
ClaimsAdjudicator(concepts: Concepts)
`
IMPORTANT One of the concepts must be the subjectExists concept. The subjectExists property can be in any case. However, if the key is not in camelCase, a copy will be added to the concepts with the key in camelCase. For example:
`js
const concepts = {
subject_exists: new Concept({
description: 'The subject exists',
longDescription: 'Determines whether a subject is a known entity within the domain.',
type: 'boolean',
relationships: ['eq', 'not_eq'],
qualifiers: ['age'],
getValue: async (id, qualifiers) => {
if (qualifiers && qualifiers.age) {
return subjects[id] !== undefined && subjects[id].age === qualifiers.age
} else {
return subjects[id] !== undefined
}
}
})
}

;(async () => {
const engine = new ClaimsAdjudicator(concepts)
const conceptInfo = await engine.getConcepts()
console.log(JSON.stringify(conceptInfo, null, 2))

//[
// {
// "id": "subject_exists",
// "description": "The subject exists",
// "longDescription": "Determines whether a subject is a known entity within the domain.",
// "type": "boolean",
// "relationships": [
// "eq",
// "not_eq"
// ],
// "qualifiers": [
// "age"
// ]
// },
// {
// "id": "subjectExists",
// "description": "The subject exists",
// "longDescription": "Determines whether a subject is a known entity within the domain.",
// "type": "boolean",
// "relationships": [
// "eq",
// "not_eq"
// ],
// "qualifiers": [
// "age"
// ]
// }
// ]
})()
`

$3


verifyClaims: Verifies the claims body against the the concept configuration.
`ts
verifyClaims(claims: any): Promise
`
The claims parameter will accept any type in the function though it will throw a BadRequest Error if the structure of the claims cannot be interpreted. The correct structure is defined in the Appendix under API Reference.

verifyClaim: Verifies a single claim against the concept configuration.
`ts
verifyClaim(claim: any): Promise
`
The claim parameter will accept any type in the function though it will throw a BadRequest Error if the str

conceptExists: Verifies that a concept has been defined.
`ts
conceptExists(key: string): boolean
`

getConcepts: Retrieves only the concepts definition information. It does not retrieve the getValue function.
`ts
getConcepts(): ConceptInfo[]
`

getConcept: Retrieves a particular concept including the getValue function.
`ts
getConcept(key: string): Concept
`




Appendix

$3


`ts

/*
* CLAIMS API
*/
interface Claims {
[key: string]: Claim
}

interface Claim {
subject: string;
mode: Mode;
claims: Claims;
}

export type ClaimItem = {
concept: string
relationship: Relationship.GT | Relationship.GTE | Relationship.LT | Relationship.LTE | Relationship.EQ | Relationship.NE
value: string
qualifier?: Qualifiers
} | {
concept: string
relationship: Relationship.UN | Relationship.DE
qualifier?: Qualifiers
}

interface Qualifiers<> {
[key: string]: any;
}

export enum Relationship {
GT = 'gt',
GTE = 'gt_or_eq',
LT = 'lt',
LTE = 'lt_or_eq',
EQ = 'eq',
NE = 'not_eq',
UN = 'undefined',
DE = 'defined'
}

export enum Mode {
ONE = 'one',
ANY = 'any',
ALL = 'all'
}

/*
* CONCEPT API
*/
export interface ConceptInfo {
name: string
description: string
longDescription?: string
relationships: Relationship[]
qualifiers: string[]
}

export interface ConceptOptions {
name: string
description: string
longDescription?: string
relationships: [Relationship, ...Relationship[]]
qualifiers?: string[]
getValue: GetValueFunction
compare: CompareFn | Comparator
cast: CastFn
}

export type GetValueFunction = (subjectId: string, qualifiers?: Qualifiers) => Promise

export type CompareFn = (left: T, right: T) => number

export type CastFn = (value: string) => T
``

$3

* Claims Adjudicator Module (CAM)
* Claims Adjudicator Middleware
* Claims Adjudicator Client
* Claims Adjudicator WSO2 Request