> For the complete documentation index, see [llms.txt](https://guardian.hedera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guardian.hedera.com/docs/develop/guardian/workspace/policies/policy-creation/introduction/documentvalidatorblock/document-validator-block-source-validations.md).

# Document Validator Block Source Validations

The Source Validations feature of `documentValidatorBlock` lets a policy step verify that a related document already exists in the Guardian database and that specific fields on that document satisfy conditions defined against the incoming document — before the workflow is allowed to proceed.

### The Problem It Solves

Many environmental MRV workflows depend on sequencing: a monitoring report is only valid after a project registration has been approved; an emission reduction claim must reference a methodology document that is already on record or search by projectID specific document and validate dates. Without a cross-document check at the block level, enforcing this ordering requires either a custom logic block or a manual review gate — all of which add complexity and introduce surface area for errors.

The Source Validations feature moves this responsibility into `documentValidatorBlock` itself. The block can query the Guardian database for documents that match a schema and ownership criteria, then test field-level conditions that span both the incoming document and the queried results, routing the event to the error output if the check fails.

### How It Works

A `documentValidatorBlock` can hold any number of Source Validation entries. Each entry is evaluated independently in order.

**Query phase.** The block builds a database filter from the entry's configuration:

* **Source Collection** — whether to query `VcDocument` or `VpDocument` records.
* **Schema** — restricts the query to documents that match a specific schema.
* **Ownership and assignment flags** — optionally limits results to documents owned by the current user, owned by their group, assigned to the user, or assigned to their group.
* **Source Filters** — field-level conditions on the source documents themselves (e.g. `credentialSubject.0.status` equals `Approved`). Each filter compares a source-document field to either a literal value or a field from the incoming document.

**Condition phase.** Once the query returns a set of candidate source documents, each one is tested against the entry's cross-document **Conditions**. A condition has two sides: each side can be a literal value, a path on the incoming document (`Input Document`), or a path on the candidate source document (`Source Document`). Supported operators are: `equal`, `not_equal`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`.

**Pass/fail semantics.** The entry passes if **at least one** candidate source document satisfies **all** conditions. If the query returns no documents, or every candidate fails at least one condition, the entry fails.

**Error reporting.** On failure the block constructs a detailed message describing which conditions failed and on how many source documents. If a custom Fail Message is set on the entry, it is prepended to the detail. The error is emitted as a `BlockActionError` that routes the event to the `ErrorEvent` output.

The full validation sequence for a document is:

1. Document existence check
2. Document type check (VC Document, VP Document, Related VC Document, Related VP Document)
3. Ownership checks (user or group)
4. Assignment checks (user or group)
5. Schema validation
6. Same-document Conditions (field conditions on the incoming document only)
7. Source Validations (cross-document, one entry at a time)

Any step that fails stops evaluation immediately and emits the error event.

### Key Distinctions

**Conditions vs. Source Validations.** The block has two separate condition mechanisms. The top-level **Conditions** array checks fields on the incoming document only — no database query is involved. **Source Validations** perform a database query and then compare fields across two documents. Use top-level Conditions for simple field checks; use Source Validations when the check depends on the state of another document.

**Source Filters vs. Source Validation Conditions.** Within a Source Validation entry, **Source Filters** narrow the database query (they affect which documents are candidates). **Conditions** test relationships between the candidate and the incoming document after the query returns. Filters reduce the candidate set; conditions determine whether any candidate in that set is sufficient.

**Pass if any, not pass if all.** The entry passes as soon as one candidate document satisfies all conditions. It does not require every queried document to satisfy the conditions.

### Related

* Task: [Configure Source Validations in documentValidatorBlock](/docs/develop/guardian/workspace/policies/policy-creation/introduction/documentvalidatorblock/configure-source-validations-in-documentvalidatorblock.md)
* Reference: [documentValidatorBlock](/docs/develop/guardian/workspace/policies/policy-creation/introduction/documentvalidatorblock.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guardian.hedera.com/docs/develop/guardian/workspace/policies/policy-creation/introduction/documentvalidatorblock/document-validator-block-source-validations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.