archetypes
v1.0.0
Published
Universal, rule-based business collaboration APIs for e-commerce and customer relationship management (CRM). `commonality/archetypes` specifies semantically-rich models of universally recurring business entities, events, and relationships with OpenAPI 2.0
Downloads
129
Readme
archetypes
⍟
A business archetype is a primordial thing that occurs consistently and universally in business domains and business software systems.
(Arlow & Neustadt, Enterprise patterns and MDA: building better software with archetype patterns and UML, 2006, p. 5)
commonality/archetypes
provides universal, rule-based business collaboration APIs for e-commerce and customer relationship management (CRM). commonality/archetypes
specifies semantically-rich models of universally recurring business entities, events, and relationships with OpenAPI 2.0.
What are archetypes
?
archetypes
model how Parties
—People
and Companies
—exchange Products
and Services
with Payments
(normally Money
or other Locale
-based Currencies
like gift-cards). The exchanges are recorded from beginning to end as Orders
and managed as Customer Relationships (CRM) between buyers and sellers (with PartyRelationships
). When necessary, Rules
constrain and determine the types of relationships allowed; how products can be packaged; and whether discounts can be applied.
These business archetypes
are expressed as models in open, vendor-neutral OpenAPI/Swagger specifications, which provide:
- A common vocabulary and operating framework for how
Parties
—People
andCompanies
—exchange goods and services forMoney
(withLocale
-basedCurrencies
), as well as managing these relationships asCustomers
(CRM). - Executable documentation that articulates these models and how they interact.
- Open-source tools that automatically generate microservice "stubs" and client SDKs.
Table of contents
- 1. Security
- 2. Installation
- 3. Usage: API HTTP responses
- 4.
Party
API :package: - 5.
Quantity
API :package: - 6.
Money
API :package: - 7.
PartyRelationship
API - 8.
Rule
API - 9. Customer relationship management (CRM) API
- 10.
Product
API - 11.
Inventory
API - 12.
Order
API - 13. Product development and delivery
- 14. DevSecOps
- 15. Style guides
- 16. Semantic version and
CHANGELOG
- 17. Contributing to
commonality/archetypes
- 18. Licenses
1. Security
commonality/archetypes
provide model-driven OpenAPI specifications for pervasive business patterns. Some of these models contain sensitive personal or company data that require access control and privacy safeguards.
None of commonality/archetypes'
specifications come with OpenAPI securityDefinitions
. Before exposing any data, please apply the principle of least privilege with your own securityDefinitions
as appropriate. You must secure how sensitive data are stored and shared.
2. Installation
Open a Terminal and run this command:
npm install --save archetypes
If your team prefers Yarn:
yarn add archetypes
2.1. Generating servers and clients
swagger-api/swagger-codegen
contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.Cheng, W., & Tam, T. (2011, August 15). swagger-api/swagger-codegen. Retrieved August 27, 2017, from https://github.com/swagger-api/swagger-codegen
Swagger Codegen will generate servers and clients in many different languages and frameworks.
Follow the Installation and Getting Starting instructions to generate and build servers and clients from workstations, CI-services, or Docker containers.
2.2. Editing OpenAPI specs
- Go to https://editor.swagger.io/.
- Copy the
/archetypes/v1/{archetype}/{archetype}.yaml
specification of interest. - Paste the
*.yaml
source into the editor pane. - Select "Generate Server" or "Generate Client" and choose an option.
- If successful, you will prompted to download the ZIPped source code.
3. Usage: API HTTP responses
3.1. curl
The simplest way to test against mock objects at http://api.swindle.net/archetypes/v1/parties
with curl
in a Terminal.
$ curl \
-X GET "http://api.swindle.net/archetypes/v1/parties/2e908e75-69a9-47e2-83ae-0c3cc52da84c" \
-H "accept: application/json"
3.2. Swagger-UI
Go to the api.swindle.net Swagger-UI's "About" section and "Explore" the available Swagger Specs.
The following sections summarize all twelve business archetype patterns as they are released.
4. Party
API :package:
The
Party
archetype represents an identifiable, addressable entity that may have a legal status and that normally has autonomous control over (at least some of) its actions.Arlow, J., & Neustadt, I. (2006). Party archetype pattern. In Enterprise patterns and MDA: building better software with archetype patterns and UML (p. 122). Boston: Addison-Wesley.
4.1. Standards compliance
| Standard | Contents | | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | | OMG Party Management Facility Specification | A standard that supports party management. | | ISO 3166 | Two- and three-letter country codes and country names. | | ISO/IEC 5218:2004 | Codes for the representation of human sexes. | | ITU-T Recommendations | Telecommunication numbering plan. |
4.2. Resources
| Proposal | Contents | | ------------------------------------------- | --------------------------------------------------------------------------------------------------- | | 63 Genders | A proposal for describing Gender as a combination of Physical, Personality and Preferential groups. |
4.3. OpenAPI 2.0 Specs
YAML
(Content-Type: application/x-yaml
)
parties/
├── nominative.yaml
├── parties.yaml
└── unique-identifier.yaml
4.4. API and SDK documentation
| Business archetype | Definition |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Organizations
| Administrative and functional structures |
| Parties
| Identifiable, addressable entity that may have a legal status and that normally has autonomous control over (at least some of) its actions. |
| People
| Human beings. |
| Preferences
| Choices of (or liking for) something, often from a set of possible or offered options. |
4.5. Usage example
Retrieve a Party
by identifier with JavaScript:
const Party = require("party");
const api = new Party.PartiesApi();
// {String} The universally unique identifier associated with a Party.
const partyIdentifier = "2e908e75-69a9-47e2-83ae-0c3cc52da84c";
const callback = (error, data, response) => {
if (error) {
console.error(error);
} else {
console.log(
"API called successfully. Returned data: " + JSON.stringify(data, null, 2)
);
}
console.log(response);
};
api.getByPartyIdentifier(partyIdentifier, callback);
5. Quantity
API :package:
The
Quantity
archetype represents an amount of something measured according to some standard of measurement.Arlow, J., & Neustadt, I. (2006). Quantity archetype pattern. In Enterprise patterns and MDA: building better software with archetype patterns and UML (p. 400). Boston: Addison-Wesley.
5.1. Standards compliance
5.2. OpenAPI 2.0 Specs
YAML
(Content-Type: application/x-yaml
)
quantities/
├── metric.yaml
├── quantities.yaml
├── quantity.yaml
├── rounding-strategy.yaml
├── si-system-of-units.yaml
└── system-of-units.yaml
5.3. API and SDK documentation
JavaScript
client SDK (Node.js) client SDK.
5.4. Usage example
Retrieve an SiBaseUnit
by identifier with JavaScript:
const Quantity = require("quantity");
const api = new Quantity.SIInternationalSystemOfUnitsApi();
// {String} The name of the unit/metric.
const name = "meter";
const callback = (error, data, response) => {
if (error) {
console.error(error);
} else {
console.log(
"API called successfully. Returned data: " + JSON.stringify(data, null, 2)
);
}
console.log(response);
};
api.getBaseUnitByName(name, callback);
6. Money
API :package:
The
Money
archetype represents anamount
of a specificCurrency
that isacceptedIn
one or moreLocales
.Arlow, J., & Neustadt, I. (2006). Money archetype pattern. In Enterprise patterns and MDA: building better software with archetype patterns and UML (p. 413). Boston: Addison-Wesley.
6.1. Standards compliance
6.2. OpenAPI 2.0 Specs
YAML
(Content-Type: application/x-yaml
)
money/
├── currency.definition.yaml
├── money.definition.yaml
├── money.yaml
├── payment-card.definition.yaml
├── payment-method.definition.yaml
├── payment.definition.yaml
└── README.md
6.3. API documentation
JavaScript
client SDK (Node.js)
6.4. Usage examples
Get all ISO 4217 Currencies
with JavaScript (Node.js):
const Money = require("money");
const moneyApi = new Money.CurrencyApi();
const callback = (error, data, response) => {
if (error) {
console.error(error);
} else {
console.log(
"API called successfully. Returned data: " + JSON.stringify(data, null, 2)
);
}
console.log(response);
};
moneyApi.getCurrencies(callback);
Retrieve a Currency
by its ISO 4217 alphabetic code with JavaScript:
const Money = require("money");
const moneyApi = new Money.CurrencyApi();
// String | An alphabetic code that represents the currency.
const alphabeticCode = "USD";
const callback = (error, data, response) => {
if (error) {
console.error(error);
} else {
console.log(
"API called successfully. Returned data: " + JSON.stringify(data, null, 2)
);
}
console.log(response);
};
moneyApi.getCurrencyByAlphabeticCode(alphabeticCode, callback);
7. PartyRelationship
API
The
PartyRelationship
captures the fact that there is a semantic relationship between twoParties
in which eachParty
plays a specific role.Arlow, J., & Neustadt, I. (2006). Archetype glossary. In Enterprise patterns and MDA: building better software with archetype patterns and UML (p. 160). Boston: Addison-Wesley.
Roadmap
MVP3: PartyRelationships and Rules
8. Rule
API
The
Rule
archetype represents a constraint on the operation of the software systems of the business—its semantics are defined by a sequence ofRuleElements
.Arlow, J., & Neustadt, I. (2006). Archetype glossary. In Enterprise patterns and MDA: building better software with archetype patterns and UML (p. 449). Boston: Addison-Wesley.
Roadmap
MVP3: PartyRelationships and Rules
9. Customer relationship management (CRM) API
Customer relationship management (CRM) is about actively managing the relationships between your business and your customers, in order to understand and increase customer value, motivation, and loyalty.
Arlow, J., & Neustadt, I. (2006). Customer relationship management archetype pattern. In Enterprise patterns and MDA: building better software with archetype patterns and UML (p. 187). Boston: Addison-Wesley.
Roadmap
MVP4: Customer relationship management (CRM)
10. Product
API
The
Product
archetype pattern represents a generalized model for products.Arlow, J., & Neustadt, I. (2006). Product archetype pattern. In Enterprise patterns and MDA: building better software with archetype patterns and UML (p. 207). Boston: Addison-Wesley.
Roadmap
11. Inventory
API
The
Inventory
archetype represents a collection ofInventoryEntries
held in stock by a business.Arlow, J., & Neustadt, I. (2006). Inventory archetype pattern. In Enterprise patterns and MDA: building better software with archetype patterns and UML (p. 271). Boston: Addison-Wesley.
Roadmap
12. Order
API
The
Order
archetype represents a request by a buyer for a seller to supply some goods or services.Arlow, J., & Neustadt, I. (2006). Inventory archetype pattern. In Enterprise patterns and MDA: building better software with archetype patterns and UML (p. 271). Boston: Addison-Wesley.
Roadmap
13. Product development and delivery
We welcome contributors and pull requests!
Interested in development contributions? Great! Check out our guidelines for Contributing to
archetypes
for details.
13.1. Built With
archetypes
requires the following tech-stack to either run, build, test, or deploy:
| Dependency | Description | Version | License | Type |
| -------------- | --------------- | ----------- | ----------- | -------- |
| @babel/core@^7.1.6 | Babel compiler core. | 7.1.6 | MIT | dev |
| all-contributors-cli@^5.4.1 | Tool to easily add recognition for new contributors | 5.4.1 | MIT | dev |
| [email protected] | Generate performance statistics for async or sync functions | 0.0.6 | UNLICENSED | dev |
| babel-jest@^23.6.0 | Jest plugin to use babel for transformation. | 23.6.0 | MIT | dev |
| babel-preset-env@^1.7.0 | A Babel preset for each environment. | 1.7.0 | MIT | dev |
| babelify@^10.0.0 | Babel browserify transform | 10.0.0 | MIT | dev |
| commitplease@^3.2.0 | Validates strings as commit messages | 3.2.0 | MIT | dev |
| coveralls@^3.0.2 | takes json-cov output into stdin and POSTs to coveralls.io | 3.0.2 | BSD-2-Clause | dev |
| eslint@^5.9.0 | An AST-based pattern checker for JavaScript. | 5.9.0 | MIT | dev |
| eslint-config-standard@^12.0.0 | JavaScript Standard Style - ESLint Shareable Config | 12.0.0 | MIT | dev |
| eslint-config-xo-space@^0.20.0 | ESLint shareable config for XO with 2-space indent | 0.20.0 | MIT | dev |
| eslint-plugin-import@^2.14.0 | Import with sanity. | 2.14.0 | MIT | dev |
| eslint-plugin-jest@^22.1.0 | Eslint rules for Jest | 22.1.0 | MIT | dev |
| eslint-plugin-jsdoc@^3.9.1 | JSDoc linting rules for ESLint. | 3.9.1 | BSD-3-Clause | dev |
| eslint-plugin-no-unsafe-innerhtml@^1.0.16 | custom ESLint rule to disallows unsafe innerHTML, outerHTML and insertAdjacentHTML | 1.0.16 | MPL-2.0 | dev |
| eslint-plugin-no-unsanitized@^3.0.2 | ESLint rule to disallow unsanitized code | 3.0.2 | MPL-2.0 | dev |
| eslint-plugin-node@^8.0.0 | Additional ESLint's rules for Node.js | 8.0.0 | MIT | dev |
| eslint-plugin-promise@^4.0.1 | Enforce best practices for JavaScript promises | 4.0.1 | ISC | dev |
| eslint-plugin-scanjs-rules@^0.2.1 | ESLint plugin that contains ScanJS rules | 0.2.1 | MPL-2.0 | dev |
| eslint-plugin-security@^1.4.0 | Security rules for eslint | 1.4.0 | Apache-2.0 | dev |
| eslint-plugin-standard@^4.0.0 | ESlint Plugin for the Standard Linter | 4.0.0 | MIT | dev |
| eslint-plugin-xss@^0.1.9 | Validates XSS related issues of mixing HTML and non-HTML content in variables. | 0.1.9 | ISC | dev |
| jest@^23.6.0 | Delightful JavaScript Testing. | 23.6.0 | MIT | dev |
| jest-cli@^23.6.0 | Delightful JavaScript Testing. | 23.6.0 | MIT | dev |
| jest-config@^23.6.0 | | 23.6.0 | MIT | dev |
| markdown-magic@^0.1.25 | Automatically update markdown files with content from external sources | 0.1.25 | MIT | dev |
| markdown-magic-dependency-table@^1.3.2 | Generate table of information about dependencies automatically in markdown | 1.3.2 | MIT | dev |
| markdown-magic-directory-tree@^1.2.3 | Print an archy tree for markdown file | 1.2.3 | MIT | dev |
| [email protected] | Add github contributors to markdown file | 0.0.3 | MIT | dev |
| markdown-magic-package-scripts@^1.2.1 | Print list of scripts in package.json with descriptions | 1.2.1 | MIT | dev |
| markdown-magic-subpackage-list@^1.1.1 | Print a list of subpackages for markdown file | 1.1.1 | MIT | dev |
| markdown-toc@^1.2.0 | Generate a markdown TOC (table of contents) with Remarkable. | 1.2.0 | MIT | dev |
| prettier@^1.15.2 | Prettier is an opinionated code formatter | 1.15.2 | MIT | dev |
| semantic-release@^15.12.... | Automated semver compliant package publishing | 15.12.2 | MIT | dev |
| snyk@^1.110.... | snyk library and cli utility | 1.110.2 | Apache-2.0 | dev |
| sonar-scanner@^3.1.0 | Wrap sonar-scanner as a node module | 3.1.0 | MIT | dev |
| standard-version@^4.4.0 | replacement for npm version
with automatic CHANGELOG generation | 4.4.0 | ISC | dev |
| swagger-parser@^6.0.2 | Swagger 2.0 and OpenAPI 3.0 parser and validator for Node and browsers | 6.0.2 | MIT | dev |
| [email protected] | schronize a remote directory with a local one, then run a series of preset commands on the server | 0.0.02 | UNLICENSED | dev |
| travis-deploy-once@^5.0.9 | Run a deployment script only once in the Travis test matrix | 5.0.9 | MIT | dev |
Keep track of archetypes'
tech-stack with these news and RSS feeds.
13.2. Prerequisite
Node.js
: commonality/archetypes
product development and delivery require Node.js
(version 6.x or greater) and its package manager, npm
. for build, test, and release tasks.
13.3. Set up a development environment
Here's a brief intro about what a developer must do in order to start developing the project further:
$ git clone https://github.com/commonality/archetypes.git
$ cd archetypes/
$ npm install
13.4. npm-scripts
Software modules often have funky, irrelative names, which is why we prefix custom tasks by their responsibility and purpose.
| Prefix | Definition |
| ----------- | ------------------------------------------------------------------------------------- |
| build*
| Source code distribution tasks. |
| docs*
| API documentation and automation tasks. |
| lint*
| Code style, standards, and vulnerabilty assessments (as well as fixes, if available). |
| release
| Bump the product's semver, update docs, commit, and publish to the npm
registry. |
| security*
| Security vulnerabilty checks. |
The following CLI npm-scripts
are available to you (assuming you're human, gentle reader) and CI-services.
| Script | Description |
|--------|-------------|
| build:bundle:all
| npm run build:bundle:money && npm run build:bundle:parties && npm run build:bundle:quantities
|
| build:bundle:money
| swagger bundle --dereference --outfile ./schemas/v1/money/money.bundle.json ./schemas/v1/money/money.spec.yaml
|
| build:bundle:parties
| swagger bundle --dereference --outfile ./schemas/v1/parties/parties.bundle.json ./schemas/v1/parties/parties.yaml
|
| build:bundle:quantities
| swagger bundle --dereference --outfile ./schemas/v1/quantities/quantities.bundle.json ./schemas/v1/quantities/quantities.yaml
|
| docs
| node generate-docs.js && npm run docs:toc
|
| docs:contributors
| all-contributors
|
| docs:contributors:add
| all-contributors add
|
| docs:contributors:generate
| all-contributors generate
|
| docs:toc
| ./node_modules/.bin/markdown-toc -i README.md
|
| lint
| npm run lint:js && npm run lint:swagger:all
|
| lint:js
| eslint . --fix
|
| lint:md
| prettier --write README.md
|
| lint:sonar
| node_modules/sonar-scanner/bin/sonar-scanner
|
| lint:swagger:all
| npm run lint:swagger:parties
|
| lint:swagger:money
| swagger validate schemas/v1/money/money.spec.yaml --debug
|
| lint:swagger:parties
| swagger validate schemas/v1/parties/parties.yaml --debug
|
| lint:swagger:quantities
| swagger validate schemas/v1/quantities/quantities.yaml --debug
|
| postbump
| echo $npm_package_version
|
| prepublishOnly
| npm run docs
|
| preversion
| npm run docs
|
| security
| npm run security:nsp:scan && npm run security:snyk:all
|
| security:audit
| npm run security:audit:scan
|
| security:audit:scan
| npm audit
|
| security:snyk
| snyk
|
| security:snyk:all
| npm run security:snyk:auth && npm run security:snyk:monitor && npm run security:snyk:scan
|
| security:snyk:auth
| snyk auth $SNYK_TOKEN
|
| security:snyk:monitor
| snyk monitor --org=commonality
|
| security:snyk:scan
| snyk test
|
| standard-version
| standard-version
|
| test
| jest --config=jest.config.json
|
| posttest
| npm run security && npm run docs
|
14. DevSecOps
commonality/archetypes
triggers Travis CI builds to execute the ESLint
, the Jest
test runner, and Node Security Platform (NSP)
analysis. Code coverage reports are then sent to Coveralls and SonarCloud.
14.1. Builds
commonality/archetypes
uses Travis CI for continuous integration.
For details, please review the .travis.yml
build file.
14.2. Tests and quality gates
This repository enforces Swagger quality; Javascript quality; and Javascript unit tests and code coverage.
14.2.1. Swagger validation
commonality/archetypes
validates Swagger docs withswagger-cli
.
swagger-cli
validation runs before every test execution:
# These two npm-scripts run lint automatically:
$ npm run pretest
$ npm test
# Only lint the Party OpenAPI specification:
$ npm run lint:swagger:party
# You can also validate your Swagger docs independently with:
$ npm run lint:swagger:all
swagger-api/validator-badge
s display whether there are syntactic issues with you Swagger/OpenAPI 2.0 document.
14.2.2. Linting
commonality/archetypes
lints withESLint
and displays real-time results with README badges.
# Code quality analysis runs before every test execution:
$ npm test
# Only validate JavaScript and OpenAPI specs
$ npm run lint
# Only run ESLint:
$ npm run lint:js
14.3.3. Spec (unit test) execution and code coverage
commonality/archetypes
usesjest
for BDD spec execution and code coverage analysis. The results are displayed real-time with README badges.
Generate detailed code coverage reports at coverage/lcov-report/index.html
and lcov.info
and clover.xml
files (which you can send to CI test coverage services like Coveralls and [OneSonarQube][one-sonar-url] or SonarCloud):
$ npm test
14.3.4. Deploy/Publish
with Angular commit conventions
Contributors must follow the Angular commit conventions in order to support automated
CHANGELOG
,package.json
, Git releasetags
, and semantic version updates.
14.3.4.1. Prerequisites
Once a PR has been approved (and passes all checks), topic branches are are merged into master
on GitHub.
- On the GitHub PR page, select Squash and Merge.
- Add a
<title>
,<body>
, and<footer>
that comply with the Conventional Commits Specfication.
14.3.4.2. Publish on npm
When you're ready to release (i.e., publish to npm
or a local Node package registry), open a Terminal and follow these steps:
- Checkout and pull the latest from
master
:
$ git checkout master; git pull origin master
- Create and document a new semantic version:
# The npm-script "release" executes standard-version
$ npm release
npm release
executes an npm-script that will:
Bump the version in
package.json
Update
CHANGELOG.md
(withconventional-changelog
)Commit
package.json
andCHANGELOG.md
Tag a new release
Push all changes, the new version
tag
tomaster
, and publish onnpm
:
$ git push --follow-tags origin master; npm publish
For
standard-version
configuration details, read "Cut a Release" on theconventional-changelog/standard-version's README
page.
15. Style guides
15.1. JavaScript source code
Whenever you run
npm test
,ESLint
will automatically reformat your JavaScript to ensure that all souce code conforms to the JavaScript Standard Style.
Open a Terminal and run any of these commands to ensure your JavaScript source code meets the JavaScript Standard Style:
- Only lint JavaScript source code (with
ESLint
):
# Runs eslint . --fix
$ npm run lint:js
- Lint source and validate OpenAPI specs:
# Lint source and validate OpenAPI specs:
$ npm run pretest
- Or run all quality gates (including source code linting):
# Or run lint and all other quality gates:
$ npm test
15.2. Color palette
The archetypes
documentation uses this color palette:
The colors are (from left to right):
#CFDBD5
: Light Grey#E8EDDF
: Platinum#F5CB5C
: Stil de Grain Yellow#242423
: Raisin Black#333533
: Jet
View the palette as PDF, PNG, SCSS, or on coolors.com.
16. Semantic version and CHANGELOG
The latest version of commonality/archetypes
is 0.0.0
. View the CHANGELOG
for details.
17. Contributing to commonality/archetypes
We welcome contributors and pull requests!
Contributions are community-driven stories with a beginning, a middle, and an end, all told through issues, comments, and pull requests. If you're interested in collaborating, please review the:
- Code of Conduct
- Contributing to
commonality/archetypes
17.1. Contribution workflows summarized
We use the Git feature-branch-workflow to accept modifications, where contributors:
- Create an issue related to the problem you want to fix (good for traceability and cross-reference)
- Label the issue as
Type: Defect
orType: Feature
- Fork the repository
- Create a branch (optionally with the reference to the issue in the name)
- Work it
- Commit incrementally with readable and detailed commit messages
- Submit a pull-request against the
master
branch of this repository.
We'll take care of tagging your issue with the appropriated labels and answer within a week (hopefully less!) to the problem you encounter.
17.2. Contributors
Thanks goes to these wonderful people (emoji key):
| Greg Swindle💻 🎨 📖 💡 ⚠️ | greenkeeper[bot]⚠️ | | :---: | :---: |
This project follows the all-contributors specification. Contributions of any kind welcome!
18. Licenses
Third-party licenses: Please see the NOTICE document for 3rd-Party Software information, or select the FOSSA badge below.
Graphic art by icons8.