Skip to content

Commit e0adda7

Browse files
Simran-BSimran-B
authored
DOC-425 | Stricter collection creation option validation (#528)
* Add deprecation log topic * Release notes about stricter validation * Minor improvement to the JS API descriptions * Fix HTTP API required attributes, minor clarifications * Don't mention internally used attributes isSmartChild and internalValidatorType in release notes
1 parent e96eda5 commit e0adda7

File tree

12 files changed

+112
-84
lines changed

12 files changed

+112
-84
lines changed

‎site/content/3.12/develop/http-api/collections.md‎

Lines changed: 22 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -375,7 +375,6 @@ paths:
375375
required:
376376
- type
377377
- allowUserKeys
378-
- lastValue
379378
properties:
380379
type:
381380
description: |
@@ -403,16 +402,16 @@ paths:
403402
increment:
404403
description: |
405404
The increment value for the `autoincrement` key generator.
406-
Not used for other key generator types.
405+
Not used by other key generator types.
407406
type: integer
408407
offset:
409408
description: |
410409
The initial offset value for the `autoincrement` key generator.
411-
Not used for other key generator types.
410+
Not used by other key generator types.
412411
type: integer
413412
lastValue:
414413
description: |
415-
The current offset value of the `autoincrement` or `padded` key generator.
414+
The offset value of the `autoincrement` or `padded` key generator.
416415
This is an internal property for restoring dumps properly.
417416
type: integer
418417
cacheEnabled:
@@ -706,7 +705,6 @@ paths:
706705
required:
707706
- type
708707
- allowUserKeys
709-
- lastValue
710708
properties:
711709
type:
712710
description: |
@@ -734,16 +732,16 @@ paths:
734732
increment:
735733
description: |
736734
The increment value for the `autoincrement` key generator.
737-
Not used for other key generator types.
735+
Not used by other key generator types.
738736
type: integer
739737
offset:
740738
description: |
741739
The initial offset value for the `autoincrement` key generator.
742-
Not used for other key generator types.
740+
Not used by other key generator types.
743741
type: integer
744742
lastValue:
745743
description: |
746-
The current offset value of the `autoincrement` or `padded` key generator.
744+
The offset value of the `autoincrement` or `padded` key generator.
747745
This is an internal property for restoring dumps properly.
748746
type: integer
749747
cacheEnabled:
@@ -1054,7 +1052,6 @@ paths:
10541052
required:
10551053
- type
10561054
- allowUserKeys
1057-
- lastValue
10581055
properties:
10591056
type:
10601057
description: |
@@ -1082,16 +1079,16 @@ paths:
10821079
increment:
10831080
description: |
10841081
The increment value for the `autoincrement` key generator.
1085-
Not used for other key generator types.
1082+
Not used by other key generator types.
10861083
type: integer
10871084
offset:
10881085
description: |
10891086
The initial offset value for the `autoincrement` key generator.
1090-
Not used for other key generator types.
1087+
Not used by other key generator types.
10911088
type: integer
10921089
lastValue:
10931090
description: |
1094-
The current offset value of the `autoincrement` or `padded` key generator.
1091+
The offset value of the `autoincrement` or `padded` key generator.
10951092
This is an internal property for restoring dumps properly.
10961093
type: integer
10971094
cacheEnabled:
@@ -1798,7 +1795,6 @@ paths:
17981795
required:
17991796
- type
18001797
- allowUserKeys
1801-
- lastValue
18021798
properties:
18031799
type:
18041800
description: |
@@ -1826,16 +1822,16 @@ paths:
18261822
increment:
18271823
description: |
18281824
The increment value for the `autoincrement` key generator.
1829-
Not used for other key generator types.
1825+
Not used by other key generator types.
18301826
type: integer
18311827
offset:
18321828
description: |
18331829
The initial offset value for the `autoincrement` key generator.
1834-
Not used for other key generator types.
1830+
Not used by other key generator types.
18351831
type: integer
18361832
lastValue:
18371833
description: |
1838-
The current offset value of the `autoincrement` or `padded` key generator.
1834+
The offset value of the `autoincrement` or `padded` key generator.
18391835
This is an internal property for restoring dumps properly.
18401836
type: integer
18411837
cacheEnabled:
@@ -2370,11 +2366,6 @@ paths:
23702366
additional options for key generation. If specified, then `keyOptions`
23712367
should be a JSON object containing the following attributes:
23722368
type: object
2373-
required:
2374-
- type
2375-
- allowUserKeys
2376-
- increment
2377-
- offset
23782369
properties:
23792370
type:
23802371
description: |
@@ -2427,13 +2418,13 @@ paths:
24272418
type: boolean
24282419
increment:
24292420
description: |
2430-
increment value for `autoincrement` key generator. Not used for other key
2431-
generator types.
2421+
The increment value for the `autoincrement` key generator.
2422+
Not allowed for other key generator types.
24322423
type: integer
24332424
offset:
24342425
description: |
2435-
Initial offset value for `autoincrement` key generator.
2436-
Not used for other key generator types.
2426+
The initial offset value for the `autoincrement` key generator.
2427+
Not allowed for other key generator types.
24372428
type: integer
24382429
type:
24392430
description: |
@@ -2690,7 +2681,6 @@ paths:
26902681
required:
26912682
- type
26922683
- allowUserKeys
2693-
- lastValue
26942684
properties:
26952685
type:
26962686
description: |
@@ -2718,16 +2708,16 @@ paths:
27182708
increment:
27192709
description: |
27202710
The increment value for the `autoincrement` key generator.
2721-
Not used for other key generator types.
2711+
Not used by other key generator types.
27222712
type: integer
27232713
offset:
27242714
description: |
27252715
The initial offset value for the `autoincrement` key generator.
2726-
Not used for other key generator types.
2716+
Not used by other key generator types.
27272717
type: integer
27282718
lastValue:
27292719
description: |
2730-
The current offset value of the `autoincrement` or `padded` key generator.
2720+
The offset value for the `autoincrement` or `padded` key generator.
27312721
This is an internal property for restoring dumps properly.
27322722
type: integer
27332723
cacheEnabled:
@@ -4028,7 +4018,6 @@ paths:
40284018
required:
40294019
- type
40304020
- allowUserKeys
4031-
- lastValue
40324021
properties:
40334022
type:
40344023
description: |
@@ -4056,16 +4045,16 @@ paths:
40564045
increment:
40574046
description: |
40584047
The increment value for the `autoincrement` key generator.
4059-
Not used for other key generator types.
4048+
Not used by other key generator types.
40604049
type: integer
40614050
offset:
40624051
description: |
40634052
The initial offset value for the `autoincrement` key generator.
4064-
Not used for other key generator types.
4053+
Not used by other key generator types.
40654054
type: integer
40664055
lastValue:
40674056
description: |
4068-
The current offset value of the `autoincrement` or `padded` key generator.
4057+
The offset value of the `autoincrement` or `padded` key generator.
40694058
This is an internal property for restoring dumps properly.
40704059
type: integer
40714060
cacheEnabled:

‎site/content/3.12/develop/http-api/monitoring/logs.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -444,6 +444,11 @@ paths:
444444
description: |
445445
One of the possible log topics.
446446
type: string
447+
deprecation:
448+
description: |
449+
Warns about deprecated features and the usage of options that
450+
will not be allowed or have no effect in a future version.
451+
type: string
447452
development:
448453
description: |
449454
One of the possible log topics.

‎site/content/3.12/develop/javascript-api/@arangodb/collection-object.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -208,11 +208,11 @@ Returns an object containing all collection properties.
208208
auto-generate keys in this case are not aware of all keys which are already used.
209209
{{< /warning >}}
210210
- `increment` (number): The increment value for the `autoincrement` key generator.
211-
Not used for other key generator types.
211+
Not used by other key generator types.
212212
- `offset` (number): The initial offset value for the `autoincrement` key generator.
213-
Not used for other key generator types.
214-
- `lastValue` (number): the current offset value of the `autoincrement` or `padded`
215-
key generator. This an internal property for restoring dumps properly.
213+
Not used by other key generator types.
214+
- `lastValue` (number): the offset value of the `autoincrement` or `padded`
215+
key generator. This is an internal property for restoring dumps properly.
216216

217217
- `schema` (object\|null):
218218
An object that specifies the collection-level document schema for documents.

‎site/content/3.12/develop/javascript-api/@arangodb/db-object.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -272,9 +272,11 @@ error is thrown. For information about the naming constraints for collections, s
272272
auto-generate keys in this case are not aware of all keys which are already used.
273273
{{< /warning >}}
274274
- `increment`: The increment value for the `autoincrement` key generator.
275-
Not used for other key generator types.
275+
Not allowed for other key generator types.
276276
- `offset`: The initial offset value for the `autoincrement` key generator.
277-
Not used for other key generator types.
277+
Not allowed for other key generator types.
278+
- `lastValue`: the offset value for the `autoincrement` or `padded`
279+
key generator. This is an internal property for restoring dumps properly.
278280

279281
- `schema` (object\|null, _optional_, default: `null`):
280282
An object that specifies the collection-level document schema for documents.

‎site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -59,11 +59,18 @@ characters using the default settings.
5959
#### Collection API
6060

6161
When creating a collection using the `POST /_api/collection` endpoint, the
62-
server log now displays a deprecation message if illegal combinations and
62+
server log now displays a `deprecation` message if illegal combinations and
6363
unknown attributes and values are detected in the request body.
6464

65-
Note that all invalid elements and combinations will be rejected in future
66-
versions.
65+
Note that all invalid elements and value combinations will be rejected in future
66+
versions. The following options are already validated more strictly in v3.12
67+
and incorrect use can lead to errors:
68+
69+
- `keyOptions`: The `increment` and `offset` sub-attributes are only allowed if
70+
the `type` sub-attribute is `"autoincrement"`. The `lastValue` sub-attribute
71+
is only allowed if the `type` sub-attribute is `"traditional"`, `"autoincrement"`,
72+
or `"padded"`.
73+
- `shardKeys`: Each array element needs to be a string.
6774

6875
#### Index API
6976

@@ -195,6 +202,10 @@ longer use the `ldap` log topic. Changing the log level of the `ldap` topic or
195202
any other unknown topic is not an error, however. Also see
196203
[Incompatible changes in ArangoDB 3.12](incompatible-changes-in-3-12.md#ldap-authentication-support-removed).
197204

205+
A new `deprecation` log topic has been added. It warns about deprecated features
206+
and the usage of options that will not be allowed or have no effect in a future
207+
version.
208+
198209
#### Error code `12` removed
199210

200211
The unused error `ERROR_OUT_OF_MEMORY_MMAP` with the number `12` has been removed.

‎site/content/3.12/release-notes/version-3.12/incompatible-changes-in-3-12.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,13 @@ or user-defined AQL functions (UDFs), compare or sort strings in them, and
206206
Unicode characters for which the standard has changed between the two ICU versions
207207
are involved.
208208

209+
## Stricter option validation when creating collections
210+
211+
Some invalid attributes and values that you can specify in the HTTP API when
212+
creating collections are no longer allowed. Previous versions ignored these
213+
invalid options. See [API Changes in ArangoDB 3.12](api-changes-in-3-12.md#collection-api)
214+
for details.
215+
209216
## Control character escaping in audit log
210217

211218
The audit log feature of the Enterprise Edition previously logged query strings

0 commit comments

Comments
 (0)