ftracker-identifiers 0.0.2

Validated, no_std-first identifier types: CNPJ, ISIN, CFI, and ISO 3166-1 country codes.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# Feature Flags

All of `Isin`'s optional integrations are off by default and purely additive. Enabling one never changes what counts as
a valid ISIN, only what you can *do* with an `Isin` once you have one.

```toml
[dependencies]
ftracker-identifiers = { version = "0.0.1", features = ["serde", "schemars", "arbitrary", "proptest"] }
```

## `serde`

(De)serializes `Isin` as its canonical 12-character string (e.g. `"US0378331005"`), so it round-trips as a plain
identifier in JSON, YAML, or config files.

Deserialization always re-runs full validation: an untrusted payload (a malformed API request, a hand-edited config
file) can never produce an invalid `Isin`. A bad value fails to deserialize with a descriptive error instead of silently
producing garbage.

```rust,ignore
use ftracker_identifiers::Isin;

let isin = Isin::parse("US0378331005").unwrap();
let json = serde_json::to_string(&isin).unwrap();
assert_eq!(json, "\"US0378331005\"");

let back: Isin = serde_json::from_str(&json).unwrap();
assert_eq!(isin, back);

// Invalid input is rejected at deserialization time, not silently accepted.
assert!(serde_json::from_str::<Isin>("\"not-an-isin\"").is_err());
```

## `schemars`

Implements `JsonSchema` for `Isin`, so it can appear in a generated OpenAPI/JSON Schema document as a
pattern-constrained string rather than an opaque `string` type. This feature implies `serde`.

The generated schema:

```json
{
  "type": "string",
  "format": "isin",
  "minLength": 12,
  "maxLength": 12,
  "pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$",
  "description": "ISIN (International Securities Identification Number, ISO 6166), Luhn checksum-valid."
}
```

Note that the `pattern` alone doesn't capture the Luhn checksum constraint. Schema validators outside this crate (API
gateways, other-language clients) can reject malformed shapes, but true checksum validation still requires this crate
(or a reimplementation of the same algorithm; see [Structure & Formats](./format.md)).

## `arbitrary`

Implements `Arbitrary` for `Isin`, so fuzz targets (e.g. via `cargo fuzz`) can generate structurally valid,
checksum-correct `Isin` values directly, instead of generating raw strings that mostly fail validation before reaching
the code under test.

## `proptest`

Exposes reusable [`proptest`](https://docs.rs/proptest) strategies at `ftracker_identifiers::isin::proptest`:

- `isin::proptest::valid_isin()` — a `Strategy<Value = Isin>` producing checksum-correct values with a two-letter
  country code and an alphanumeric NSIN.
- `isin::proptest::valid_isin_string()` — the same, rendered as a canonical `String`, useful for
  round-trip-through-parsing property tests.

This is the recommended way to property-test *your own* code that accepts an `Isin`, without hand-rolling a
checksum-valid generator:

```rust,ignore
use ftracker_identifiers::{isin::proptest::valid_isin, Isin};
use proptest::proptest;

proptest! {
    #[test]
    fn my_function_accepts_any_valid_isin(isin in valid_isin()) {
        // exercise your own code with `isin` here
    }
}
```