#Understanding Submission Requirements

#Overview

Submission Requirements are a powerful feature of the DIF Presentation Exchange specification that enable relying parties to express complex logical combinations of required credentials within a Presentation Definition. When verifying identity claims, a relying party often needs more than just a single credential - they may need specific combinations, choices between different types of credentials, or nested logical groupings.

This document explains how Submission Requirements work, why they're important, and how to use them effectively in your Vidos implementation to create flexible and precise verification experiences.

#Why Submission Requirements Matter

Without Submission Requirements, a relying party would be limited to requiring all input descriptors defined in a Presentation Definition. This approach lacks flexibility for real-world verification scenarios where:

• Users might have different forms of acceptable credentials (like passport OR driver's license)
• Verification might require combinations of credentials (proof of identity AND proof of address)
• Complex logic might be needed (proof of identity AND either proof of employment OR proof of income)

Submission Requirements solve these challenges by providing a standardized way to express these logical combinations, making verification processes more flexible and user-friendly while maintaining strong security and compliance requirements.

#Core Concepts

#Key Components

Submission Requirements consist of these key elements:

• Rules: Define how to select inputs (all, pick)
• Groups: Organize input descriptors into logical sets
• Count, Min, Max: Control how many inputs are needed from a group
• Nested Requirements: Enable complex combinations of rules

#How They Work

1. Input descriptors are assigned to named groups
2. Submission Requirements define rules about these groups
3. Rules can be combined and nested to create complex logic
4. The holder provides credentials that satisfy the requirements

#Rules in Detail

Submission Requirements use two primary rule types:

#The "all" Rule

The "all" rule requires that all input descriptors from a specified group must be submitted. Use this when every credential in a group is mandatory.

{
    "rule": "all",
    "from": "A"
}

This simple example requires all input descriptors assigned to group "A" to be submitted.

#The "pick" Rule

The "pick" rule lets you specify how many input descriptors from a group are required. It provides flexibility with these options:

• count: Exact number required
• min: Minimum number required
• max: Maximum number allowed

{
    "rule": "pick",
    "count": 1,
    "from": "B"
}

This example requires exactly one input descriptor from group "B" to be submitted.

{
    "rule": "pick",
    "min": 2,
    "from": "C"
}

This example requires at least two input descriptors from group "C" to be submitted.

#Grouping Input Descriptors

To use Submission Requirements, you must assign input descriptors to groups:

{
    "id": "banking_credential",
    "name": "Bank Statement",
    "group": ["A"],
    "constraints": {
        // Constraints defined here
    }
}

Key points about groups:

• An input descriptor can belong to multiple groups
• Groups are identified by simple string identifiers
• Groups create logical collections of related credentials
• All input descriptors must be grouped when using Submission Requirements

#Building Complex Logic

The true power of Submission Requirements emerges when combining and nesting rules to create complex logic.

#Combining Multiple Rules

Multiple Submission Requirements at the same level are treated as "AND" conditions - all must be satisfied:

"submission_requirements": [
  {
    "rule": "all",
    "from": "A"
  },
  {
    "rule": "pick",
    "count": 1,
    "from": "B"
  }
]

This requires all credentials from group "A" AND exactly one credential from group "B".

#Nested Requirements

For more complex logic, you can nest requirements using the from_nested property:

{
    "rule": "pick",
    "count": 1,
    "from_nested": [
        { "rule": "all", "from": "A" },
        { "rule": "pick", "count": 2, "from": "B" }
    ]
}

This example requires either:

• All credentials from group "A" OR
• Any two credentials from group "B"

#Real-World Examples in Vidos

#Example 1: Identity Verification

A relying party wants to confirm a user's identity through either a government ID or a combination of credentials:

{
    "submission_requirements": [
        {
            "rule": "pick",
            "count": 1,
            "from_nested": [
                { "rule": "all", "from": "government_id" },
                {
                    "rule": "all",
                    "from_nested": [
                        { "rule": "all", "from": "basic_identity" },
                        { "rule": "all", "from": "address_proof" }
                    ]
                }
            ]
        }
    ],
    "input_descriptors": [
        {
            "id": "passport",
            "name": "Passport",
            "group": ["government_id"],
            "constraints": {
                /* ... */
            }
        },
        {
            "id": "drivers_license",
            "name": "Driver's License",
            "group": ["government_id"],
            "constraints": {
                /* ... */
            }
        },
        {
            "id": "birth_certificate",
            "name": "Birth Certificate",
            "group": ["basic_identity"],
            "constraints": {
                /* ... */
            }
        },
        {
            "id": "utility_bill",
            "name": "Utility Bill",
            "group": ["address_proof"],
            "constraints": {
                /* ... */
            }
        }
    ]
}

This configuration allows users to verify their identity with either:

• A passport or driver's license
• OR both a birth certificate AND a utility bill

#Example 2: Financial Qualification

A loan application process requiring proof of employment status and financial history:

{
    "submission_requirements": [
        {
            "name": "Employment Verification",
            "rule": "pick",
            "count": 1,
            "from": "employment"
        },
        {
            "name": "Financial History",
            "rule": "all",
            "from": "financial"
        }
    ],
    "input_descriptors": [
        {
            "id": "employment_letter",
            "name": "Employment Letter",
            "group": ["employment"],
            "constraints": {
                /* ... */
            }
        },
        {
            "id": "pay_stubs",
            "name": "Pay Stubs",
            "group": ["employment"],
            "constraints": {
                /* ... */
            }
        },
        {
            "id": "credit_score",
            "name": "Credit Score",
            "group": ["financial"],
            "constraints": {
                /* ... */
            }
        },
        {
            "id": "bank_statements",
            "name": "Bank Statements",
            "group": ["financial"],
            "constraints": {
                /* ... */
            }
        }
    ]
}

This configuration requires:

• Either an employment letter OR pay stubs for employment verification
• AND both credit score AND bank statements for financial history

#Best Practices

When working with Submission Requirements in Vidos:

1. Keep it simple - Only use the complexity you need
2. Use descriptive names - Add the name property to make requirements user-friendly
3. Include purpose statements - Add the purpose property to explain why each requirement exists
4. Test your logic - Verify that your combinations work as expected
5. Consider the user experience - Balance security requirements with usability
6. Provide clear feedback - Help users understand what credentials they need to satisfy requirements

#Integration with Vidos

In Vidos, Submission Requirements are configured through the Verifier service and its management interface. This allows you to:

1. Define flexible verification policies
2. Create reusable templates for common verification scenarios
3. Dynamically adjust requirements based on risk assessment
4. Provide clear guidance to credential holders

The Verifier service processes the Presentation Definition (including Submission Requirements) and evaluates whether the presented credentials satisfy the specified logic.

#Related Concepts

Submission Requirements are part of the broader DIF Presentation Exchange specification, which includes:

• Presentation Definitions - The overall container for verification requirements
• Input Descriptors - Detailed specifications for individual credentials
• Format Options - Supported credential formats and cryptographic methods
• Constraints - Specific field requirements within credentials

Understanding how these components work together provides a complete picture of the credential verification framework.

#Further Resources

• DIF Presentation Exchange Specification