Skip to main content

​
Lock-Key-Weight Model

The lock-key-weight model is the heart of Docyard’s access control. It’s simple, flexible, and powerful.

​
The Core Concept

Every artifact in the lake has:
  1. Locks: Metadata fields that define access requirements
  2. Keys: Values for those metadata fields
  3. Weights: Scores assigned to each lock type
  4. Threshold: Minimum combined score required for access
Collectors retrieve artifacts by presenting keys. The system calculates the score. If the score meets or exceeds the threshold, access is granted.

​
How It Works

​
Step 1: Distributor Uploads Artifact

When uploading, the distributor:
  1. Selects an artifact type template
  2. Provides values (keys) for each lock
  3. Assigns weights to each lock type
  4. Sets a threshold score
{
  "locks": {
    "policy_number": { "value": "POL-12345678", "weight": 20 },
    "effective_date": { "value": "2026-03-15", "weight": 10 },
    "mortgagee_name": { "value": "FirstCity Bank", "weight": 5 }
  },
  "threshold": 20
}

​
Step 2: Collector Attempts Retrieval

When a collector wants the artifact, they:
  1. Search for artifacts
  2. Present their keys
  3. System calculates total score
POST /api/v1/dock/retrieve/{artifact_id}
{
  "keys": {
    "policy_number": "POL-12345678"
  }
}

​
Step 3: Access Decision

The system calculates:
Presented KeyWeightMatch?
policy_number: POL-1234567820✅ Yes
effective_date: (not provided)10❌ No
mortgagee_name: (not provided)5❌ No
Total Score: 20
Threshold: 20
Decision: ✅ Access Granted (20 ≥ 20)

​
Score Calculation Examples

​
Example 1: Full Match

Collector has the policy number:
KeyWeightProvided?
policy_number20✅
effective_date10❌
mortgagee_name5❌
Score: 20
Threshold: 20
Result: ✅ Access Granted

​
Example 2: Partial Match (Enough)

Collector has mortgagee name AND effective date:
KeyWeightProvided?
policy_number20❌
effective_date10✅
mortgagee_name5✅
Score: 10 + 5 = 15
Threshold: 20
Result: ❌ Access Denied (15 < 20)

​
Example 3: Multiple Partial Matches

Collector has all three keys:
KeyWeightProvided?
policy_number20✅
effective_date10✅
mortgagee_name5✅
Score: 20 + 10 + 5 = 35
Threshold: 20
Result: ✅ Access Granted (35 ≥ 20)

​
Why Weights Matter

Weights allow fine-grained access control:

​
High-Security Artifact

{
  "locks": {
    "policy_number": { "weight": 30 },
    "effective_date": { "weight": 20 }
  },
  "threshold": 50
}
  • Requires combining multiple strong keys
  • A single key isn’t enough
  • Higher security

​
Low-Security Artifact

{
  "locks": {
    "policy_number": { "weight": 40 }
  },
  "threshold": 20
}
  • Single key grants access
  • Easier for collectors
  • Lower security

​
Lock Types

Each lock type has:
PropertyDescriptionExample
NameUnique identifierpolicy_number
Data TypeValue typestring, number, date
ValidationFormat rulesregex pattern
WeightScore contribution20

​
Common Lock Types

Lock TypeData TypeDescriptionTypical Weight
policy_numberstringInsurance policy ID15-25
loan_numberstringLoan identifier15-25
effective_datedateEffective date5-10
mortgagee_namestringLender name5-10
document_typestringCategory of document5-10
addressstringProperty address5-10
insured_namestringInsured person5-10

​
System vs Custom Lock Types

​
System Lock Types

Mandatory for all artifacts:
Lock TypeDescriptionRequired?
document_typeCategory of document✅ Yes

​
Custom Lock Types

Defined by distributors in their artifact type templates: 
{
  "name": "vin_number",
  "data_type": "string",
  "description": "Vehicle identification number",
  "validation": { "pattern": "^[A-HJ-NPR-Z0-9]{17}$" },
  "weight": 15,
  "required": true
}

​
Matching Logic

​
Exact Match

For string locks, values must match exactly: 
Artifact lock: policy_number = "POL-12345678"
Collector key: policy_number = "POL-12345678"
Result: ✅ Match

Artifact lock: policy_number = "POL-12345678"
Collector key: policy_number = "POL-87654321"
Result: ❌ No Match

​
Partial Match (Optional)

For string locks, you can enable partial matching: 
Artifact lock: mortgagee_name = "FirstCity Bank"
Collector key: mortgagee_name = "FirstCity"
Result: ✅ Match (if partial matching enabled)

​
Date Range (Optional)

For date locks, you can match ranges: 
Artifact lock: effective_date = "2026-03-15"
Collector key: effective_date_after = "2026-03-01", effective_date_before = "2026-03-31"
Result: ✅ Match

​
Access Denied Scenarios

​
Score Too Low

{
  "keys": { "mortgagee_name": "FirstCity Bank" },
  "result": {
    "score": 5,
    "threshold": 20,
    "status": "denied",
    "message": "Score (5) is below threshold (20). Provide more keys."
  }
}

​
Missing Required Keys

{
  "keys": {},
  "result": {
    "score": 0,
    "threshold": 20,
    "status": "denied",
    "message": "No matching keys provided."
  }
}

​
Benefits of Lock-Key-Weight

  1. Flexible: Combine any keys to meet threshold
  2. Fine-grained: Weights allow security tuning
  3. Simple: No complex permission matrices
  4. Open: Any collector can attempt access
  5. Secure: Only those with real keys succeed

​
Next Steps