Skip to content

Commit 6f563df

Browse files
devalogdevalog
committed
cut down and clarify validation section
1 parent 026f556 commit 6f563df

File tree

1 file changed

+87
-220
lines changed

1 file changed

+87
-220
lines changed

‎fern/products/fern-def/pages/types.mdx‎

Lines changed: 87 additions & 220 deletions
Original file line numberDiff line numberDiff line change
@@ -279,57 +279,32 @@ interface Person {
279279
}
280280
```
281281
</CodeBlock>
282-
### Validation
283282

284-
You can add validation constraints to your types to ensure data integrity and provide better error messages in generated SDKs. You can add validation rules to both type aliases and type references.
283+
### Validating types
285284

286-
### String validation
285+
You can add validation constraints to your types (both aliases and references) to ensure data integrity and provide better error messages in generated SDKs:
287286

288-
String types support several validation constraints:
289-
290-
<ParamField path="minLength" type="integer">
291-
Minimum number of characters required
292-
</ParamField>
293-
294-
<ParamField path="maxLength" type="integer">
295-
Maximum number of characters allowed
296-
</ParamField>
297-
298-
<ParamField path="pattern" type="string">
299-
Regular expression pattern that the string must match
300-
</ParamField>
301-
302-
<ParamField path="format" type="string">
303-
String format specification (e.g., "email", "uri", "date-time")
304-
</ParamField>
305-
306-
#### Example: String validation on type alias
307-
308-
```yaml
287+
```yaml {4-6}
309288
types:
310-
Email:
289+
Sentence:
311290
type: string
312291
validation:
313-
format: email
314-
maxLength: 254
315-
316-
Username:
317-
type: string
318-
validation:
319-
minLength: 3
320-
maxLength: 20
321-
pattern: "^[a-zA-Z0-9_]+$"
322-
323-
PhoneNumber:
324-
type: string
325-
validation:
326-
pattern: "^\\+?[1-9]\\d{1,14}$"
292+
minLength: 4
293+
maxLength: 256
327294
```
328295

329-
#### Example: String validation on object properties
296+
<AccordionGroup>
297+
<Accordion title="String validation">
330298

331-
```yaml
299+
String types support several validation constraints.
300+
301+
```yaml {4-6, 11-13, 16-19}
332302
types:
303+
Word:
304+
type: string
305+
validation:
306+
minLength: 2
307+
maxLength: 26
333308
User:
334309
properties:
335310
email:
@@ -343,64 +318,37 @@ types:
343318
minLength: 3
344319
maxLength: 20
345320
pattern: "^[a-zA-Z0-9_]+$"
346-
bio:
347-
type: optional<string>
348-
validation:
349-
maxLength: 500
350321
```
351322

352-
### Number validation
353-
354-
Number types (including `integer`, `long`, and `double`) support validation constraints:
355-
356-
<ParamField path="min" type="number">
357-
Minimum value (inclusive by default)
323+
<ParamField path="minLength" type="integer">
324+
Minimum number of characters required
358325
</ParamField>
359326

360-
<ParamField path="max" type="number">
361-
Maximum value (inclusive by default)
327+
<ParamField path="maxLength" type="integer">
328+
Maximum number of characters allowed
362329
</ParamField>
363330

364-
<ParamField path="exclusiveMin" type="boolean">
365-
When true, the minimum value is exclusive (value must be greater than min)
331+
<ParamField path="pattern" type="string">
332+
Regular expression pattern that the string must match
366333
</ParamField>
367334

368-
<ParamField path="exclusiveMax" type="boolean">
369-
When true, the maximum value is exclusive (value must be less than max)
335+
<ParamField path="format" type="string">
336+
String format specification (e.g., "email", "uri", "date-time")
370337
</ParamField>
371338

372-
<ParamField path="multipleOf" type="number">
373-
Value must be a multiple of this number
374-
</ParamField>
339+
</Accordion>
375340

376-
#### Example: Number validation on type alias
341+
<Accordion title="Number validation">
377342

378-
```yaml
343+
Number types (including `integer`, `long`, and `double`) support several validation constraints.
344+
345+
```yaml {4-6, 12-15, 18-20}
379346
types:
380347
Age:
381348
type: integer
382349
validation:
383350
min: 0
384351
max: 150
385-
```
386-
Price:
387-
type: double
388-
validation:
389-
min: 0
390-
exclusiveMin: true # Price must be greater than 0
391-
multipleOf: 0.01 # Price must be in cents
392-
393-
Percentage:
394-
type: double
395-
validation:
396-
min: 0
397-
max: 100
398-
```
399-
400-
#### Example: Number validation on object properties
401-
402-
```yaml
403-
types:
404352
Product:
405353
properties:
406354
name: string
@@ -415,157 +363,76 @@ types:
415363
validation:
416364
min: 1
417365
max: 1000
418-
discount:
419-
type: optional<double>
420-
validation:
421-
min: 0
422-
max: 100
423366
```
424367

425-
### Validation in generated SDKs
368+
<ParamField path="min" type="number">
369+
Minimum value (inclusive by default)
370+
</ParamField>
426371

427-
When you add validation constraints to your Fern Definition, they are automatically enforced in generated SDKs:
372+
<ParamField path="max" type="number">
373+
Maximum value (inclusive by default)
374+
</ParamField>
428375

429-
<CodeBlocks>
430-
```python title="Python SDK"
431-
from your_api import YourApiClient
432-
from your_api.errors import ValidationError
433-
434-
client = YourApiClient(api_key="your-api-key")
435-
436-
try:
437-
# This will raise a ValidationError
438-
user = client.users.create(
439-
email="invalid-email", # Fails email format validation
440-
username="ab", # Fails minLength validation
441-
age=-5 # Fails min value validation
442-
)
443-
except ValidationError as e:
444-
print(f"Validation failed: {e}")
445-
```
376+
<ParamField path="exclusiveMin" type="boolean">
377+
When true, the minimum value is exclusive (value must be greater than min)
378+
</ParamField>
379+
380+
<ParamField path="exclusiveMax" type="boolean">
381+
When true, the maximum value is exclusive (value must be less than max)
382+
</ParamField>
383+
384+
<ParamField path="multipleOf" type="number">
385+
Value must be a multiple of this number
386+
</ParamField>
446387

447-
```typescript title="TypeScript SDK"
448-
import { YourApiClient, ValidationError } from "your-api-sdk";
388+
</Accordion>
389+
</AccordionGroup>
449390

450-
const client = new YourApiClient({
451-
apiKey: "your-api-key"
452-
});
391+
#### Validation in generated SDKs
453392

393+
When you add validation constraints to your Fern Definition, they are automatically enforced in generated SDKs:
394+
395+
<CodeBlock title="Fern Definition">
396+
```yaml {8-11, 15-17}
397+
types:
398+
Person:
399+
docs: A person represents a human being
400+
properties:
401+
name:
402+
docs: The person's full name
403+
type: string
404+
validation:
405+
minLength: 2
406+
maxLength: 100
407+
pattern: "^[A-Za-z ]+$"
408+
age:
409+
docs: Age in years
410+
type: integer
411+
validation:
412+
min: 0
413+
max: 150
414+
```
415+
</CodeBlock>
416+
<CodeBlock title="Generated TypeScript SDK from Fern Definition">
417+
```typescript
418+
interface Person {
419+
/** The person's full name */
420+
name: string;
421+
/** Age in years */
422+
age: number;
423+
}
424+
425+
// Validation is automatically enforced when creating Person objects
426+
const client = new YourApiClient();
454427
try {
455-
// This will throw a ValidationError
456-
const user = await client.users.create({
457-
email: "invalid-email", // Fails email format validation
458-
username: "ab", // Fails minLength validation
459-
age: -5 // Fails min value validation
428+
const person = await client.createPerson({
429+
name: "A", // Fails minLength validation
430+
age: -5, // Fails min validation
460431
});
461432
} catch (error) {
462433
if (error instanceof ValidationError) {
463434
console.log(`Validation failed: ${error.message}`);
464435
}
465436
}
466437
```
467-
468-
```java title="Java SDK"
469-
import com.yourapi.YourApiClient;
470-
import com.yourapi.core.ValidationException;
471-
472-
YourApiClient client = YourApiClient.builder()
473-
.apiKey("your-api-key")
474-
.build();
475-
476-
try {
477-
// This will throw a ValidationException
478-
User user = client.users().create(CreateUserRequest.builder()
479-
.email("invalid-email") // Fails email format validation
480-
.username("ab") // Fails minLength validation
481-
.age(-5) // Fails min value validation
482-
.build());
483-
} catch (ValidationException e) {
484-
System.out.println("Validation failed: " + e.getMessage());
485-
}
486-
```
487-
</CodeBlocks>
488-
489-
### Best practices
490-
491-
<Tip>
492-
**Use validation to improve API reliability**: Validation constraints help catch errors early and provide clear feedback to API consumers.
493-
</Tip>
494-
495-
<Tip>
496-
**Be consistent with formats**: Use standard format values like "email", "uri", "date-time" for better interoperability.
497-
</Tip>
498-
499-
<Tip>
500-
**Document your patterns**: When using regex patterns, consider adding documentation to explain the expected format.
501-
</Tip>
502-
503-
```yaml
504-
types:
505-
ProductCode:
506-
docs: Product code must be 3 uppercase letters followed by 4 digits (e.g., ABC1234)
507-
type: string
508-
validation:
509-
pattern: "^[A-Z]{3}\\d{4}$"
510-
```
511-
512-
<Warning>
513-
**Regex escaping**: Remember to properly escape backslashes in YAML strings. Use `\\d` instead of `\d` for digit patterns.
514-
</Warning>
515-
516-
### Common validation patterns
517-
518-
Here are some commonly used validation patterns:
519-
520-
```yaml
521-
types:
522-
# Email validation
523-
Email:
524-
type: string
525-
validation:
526-
format: email
527-
maxLength: 254
528-
529-
# URL validation
530-
WebsiteUrl:
531-
type: string
532-
validation:
533-
format: uri
534-
pattern: "^https?://"
535-
536-
# Phone number (international format)
537-
PhoneNumber:
538-
type: string
539-
validation:
540-
pattern: "^\\+?[1-9]\\d{1,14}$"
541-
542-
# Credit card number (basic format)
543-
CreditCardNumber:
544-
type: string
545-
validation:
546-
pattern: "^\\d{13,19}$"
547-
minLength: 13
548-
maxLength: 19
549-
550-
# Positive currency amount
551-
Amount:
552-
type: double
553-
validation:
554-
min: 0
555-
exclusiveMin: true
556-
multipleOf: 0.01
557-
558-
# Percentage (0-100)
559-
Percentage:
560-
type: double
561-
validation:
562-
min: 0
563-
max: 100
564-
565-
# Port number
566-
Port:
567-
type: integer
568-
validation:
569-
min: 1
570-
max: 65535
571-
```
438+
</CodeBlock>

0 commit comments

Comments
 (0)