# `validate`

Validates an ArcGIS item and its owner's user profile against Living Atlas criteria. Returns a detailed `ValidationResult` object containing per-rule scores, statuses, and an overall score out of 100, as well as a flag indicating whether the item meets the minimum threshold to be nominated to Living Atlas.

## Basic Usage

```typescript
import { validate } from '@vannizhang/living-atlas-content-validator';

validate(
    item: IItem,
    userProfile: IUser,
    options?: ValidateOptions
): ValidationResult
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `item` | `IItem` | Yes | The ArcGIS Online [portal item](https://developers.arcgis.com/rest/users-groups-and-items/item/) to validate. |
| `userProfile` | `IUser` | Yes | The [user profile](https://developers.arcgis.com/rest/users-groups-and-items/user/) of the item's owner. |
| `options` | `ValidateOptions` | No | Optional configuration object (see [Options](#options) below). |

## Options

| Option | Type | Description |
|--------|------|-------------|
| `thumbnailDimension` | `{ width: number; height: number }` | The dimensions of the largest thumbnail retrievable from ArcGIS Online. Used to assess thumbnail quality. |
| `customPatternsForLocationInfo` | `string[]` | Custom patterns to detect location information in the item's title and summary. |
| `customPatternsForDataVintageInfo` | `string[]` | Custom patterns to detect data vintage (time) information in the item's title and summary. |
| `customPatternsForSourceInfo` | `string[]` | Custom patterns to detect source information in the item's title and summary. |
| `customPatternsForTopicInfo` | `string[]` | Custom patterns to detect topic information in the item's title and summary. |
| `featureLayers` | [`FeatureLayerJSON[]`](../types/README.md#featurelayerjson) | Feature layer JSON objects for the feature service. Required for field alias, value type, description, index, and extent validations. |
| `featureServiceAdminJSON` | [`FeatureServiceAdminJSON`](../types/README.md#featureserviceadminjson) | Admin resource JSON of the feature service. Used for advisories (CDN setting, export setting, extents). |
| `featureServiceRootJSON` | [`FeatureServiceJSON`](../types/README.md#featureservicejson) | Root resource JSON of the feature service. Used for extent validation when the admin JSON is not available. |
| `webmapData` | [`WebmapData`](../types/README.md#webmapdata) | The web map's JSON data (basemap, operational layers, etc.). Required for web map layer and popup validations. |
| `webmapLayerItems` | `IItem[]` | ArcGIS item objects for each layer in the web map. Required for web map layer validation. |
| `webmapLayerDataByItemId` | [`WebmapLayerDataByItemId`](../types/README.md#webmaplayerdatabyitemid) | Item data keyed by item ID for web map layer popup configuration validation. |
| `featureLayerItemData` | [`FeatureLayerItemData`](../types/README.md#featurelayeritemdata) | Item data for feature layer popup configuration validation. |
| `imageryLayerItemData` | [`ImageryLayerItemData`](../types/README.md#imagerylayeritemdata) | Item data for imagery layer popup configuration validation. |
| `shouldCheckAdvisories` | `boolean` | When `true`, advisory checks are executed and included in the result. Advisories do not affect the score. |

## Return Value

Returns a [`ValidationResult`](../types/README.md#validationresult) object. See the [Types documentation](../types/README.md#validationresult) for the full type definition, including all `validatedItem`, `validatedProfile`, and `advisories` properties.

### Checking overall score and nomination eligibility

You can use the `totalScore` and `canBeNominated` properties on the returned `ValidationResult` object to quickly assess whether an item meets the minimum criteria for Living Atlas nomination:

```typescript
const result = validate(item, userProfile);

console.log(result.totalScore);     // e.g. 87.5 (0–100)
console.log(result.canBeNominated); // true | false
```

`canBeNominated` is `true` only when **all** of the following are satisfied:

- `totalScore` is **≥ 80**
- The item is publicly shared (`access` passes)
- The item is **not** marked as deprecated
- Delete protection is enabled
- The thumbnail meets the required dimensions
- The item has a non-empty summary (`snippet`)
- The item has a non-empty description
- The item owner has a profile description
- For Web Maps: all layers are accessible and not deprecated

### Inspecting per-rule feedback

Each property in `validatedItem`, `validatedProfile`, and `advisories` is a [`ValidationInfo`](../types/README.md#validationinfo) object containing the rule's status, score, and messages. Use these to get detailed feedback on which specific rules passed or failed, and why:

```typescript
const { title, thumbnail, description, snippet } = result.validatedItem;

// Check whether a specific rule passed
if (title.status === 'error') {
    console.log(title.messages); // array of messages explaining the failure
}

// Compare score against the maximum possible for this rule
console.log(`Thumbnail: ${thumbnail.score} / ${thumbnail.maxScore}`);

// Iterate over all item rules to collect failing ones
const failingRules = Object.values(result.validatedItem).filter(
    (rule) => rule.status === 'error' || rule.status === 'warning'
);
```

The `status` field on each rule is one of `"pass"`, `"warning"`, `"error"`, `"not-applicable"`, or `"unknown"`. Rules that do not apply to the item type (e.g. `featureServiceFieldAliases` on a Web Map) will have `status: "not-applicable"` and a `score` and `maxScore` of `0`.

## Examples

### Provide thumbnail dimensions for accurate thumbnail validation

The validator does not fetch thumbnails itself — it relies on the `thumbnailDimension` option to know the actual pixel size of the largest thumbnail available for the item on ArcGIS Online. Without this, thumbnail quality cannot be accurately assessed.

Pass the width and height that match the largest thumbnail size for the input item.

```typescript
import { validate } from '@vannizhang/living-atlas-content-validator';

const result = validate(
    item,
    userProfile,
    {
        thumbnailDimension: { width: 600, height: 400 },
    }
);
```

### Validate a Feature Layer

To validate a feature layer item, you must provide the `featureLayers` option with the layer JSON for each layer in the feature service. For popup configuration validation, also provide `featureLayerItemData`. To check for advisories (CDN setting, export setting, extents), provide `featureServiceAdminJSON` or `featureServiceRootJSON`.

See the [FeatureLayerJSON](../types/README.md#featurelayerjson), [FeatureServiceAdminJSON](../types/README.md#featureserviceadminjson), and [FeatureServiceJSON](../types/README.md#featureservicejson) for the expected structure of these objects.

```typescript
import { validate } from '@vannizhang/living-atlas-content-validator';

const result = validate(
    item,       // IItem — the Feature Service portal item
    userProfile, // IUser — the item owner's user profile
    {
        thumbnailDimension: { width: 600, height: 400 }, // dimensions of the largest thumbnail retrievable from AGO
        featureLayers,          // FeatureLayerJSON[] — layer JSON for field-level rules
        featureLayerItemData,   // FeatureLayerItemData — for popup validation
        featureServiceAdminJSON, // FeatureServiceAdminJSON — for CDN/export/extent advisories. You can omit this if you don't want to check advisories or if the item is not a feature service.
        featureServiceRootJSON,  // FeatureServiceJSON — for extent advisory when admin JSON is not available. You can omit this if you don't want to check advisories or if the item is not a feature service.
    }
);

console.log(result.totalScore);     // 0–100
console.log(result.canBeNominated); // true | false
```

### Validate an Imagery Layer

To validate an imagery layer item, provide `imageryLayerItemData` for popup configuration validation.

See the [ImageryLayerItemData](../types/README.md#imagerylayeritemdata) type for the expected structure of this object.

```typescript
import { validate } from '@vannizhang/living-atlas-content-validator';

const result = validate(
    item,        // IItem — the Imagery Layer portal item
    userProfile, // IUser — the item owner's user profile
    {
        thumbnailDimension: { width: 600, height: 400 }, // dimensions of the largest thumbnail retrievable from AGO
        imageryLayerItemData, // ImageryLayerItemData — for popup validation
    }
);

console.log(result.totalScore);     // 0–100
console.log(result.canBeNominated); // true | false
```

### Validate a Web Map

To validate a web map item, you must provide the `webmapData` option with the web map's JSON data, as well as `webmapLayerItems` with the portal items for each layer in the web map. For popup configuration validation, also provide `webmapLayerDataByItemId`.

See the [WebmapData](../types/README.md#webmapdata), [IItem](https://developers.arcgis.com/rest/users-groups-and-items/item/), and [WebmapLayerDataByItemId](../types/README.md#webmaplayerdatabyitemid) types for the expected structure of these objects.

```typescript
import { validate } from '@vannizhang/living-atlas-content-validator';

const result = validate(
    item,        // IItem — the Web Map portal item
    userProfile, // IUser — the item owner's user profile
    {
        thumbnailDimension: { width: 600, height: 400 }, // dimensions of the largest thumbnail retrievable from AGO
        webmapData,               // WebmapData — basemap and operational layer JSON
        webmapLayerItems,         // IItem[] — portal items for each layer in the web map
        webmapLayerDataByItemId,  // WebmapLayerDataByItemId — item data keyed by item ID for popup validation
    }
);

console.log(result.totalScore);     // 0–100
console.log(result.canBeNominated); // true | false
```

### Validate with custom patterns

For layer items — **Feature Service**, **Image Service**, **Map Service**, **Vector Tile Service**, **WMS**, **Group Layer**, and **Scene Service** — the validator checks the item's title and summary for location, source, topic, and data vintage information using built-in patterns to compute the searchability score. If your item uses terminology not covered by the defaults, you can supply additional custom patterns via the `options` parameter to ensure those terms are recognized.

```typescript
import { validate } from '@vannizhang/living-atlas-content-validator';

const result = validate(
    item,
    userProfile,
    {
        thumbnailDimension: { width: 600, height: 400 }, // dimensions of the largest thumbnail retrievable from AGO
        customPatternsForLocationInfo: ['California', 'Europe', 'Asia'],
        customPatternsForSourceInfo: ['NOAA', 'USGS', 'NASA'],
        customPatternsForTopicInfo: ['Climate Change', 'Demographics', 'Land Use'],
        customPatternsForDataVintageInfo: ['2023', 'bi-weekly', 'historical'],
    }
);

console.log(result.totalScore);     // 0–100
console.log(result.canBeNominated); // true | false
```