acs-reference Design Documentation

I. Introduction

Reference data services are often overlooked in the rush to get coding. Much of the code is redundant or of similarly patterned implementations. This package intends to address some common features and needs.

II. Historical Considerations

Before the existence of acs-reference, the ACS required that you preload some tables in a script to get some basic reference functionality. There were many problems with this:

III. Design Tradeoffs

Primary Goals


When updating the reference tables their is overhead due to the fact that the table is registered with the repository. This should rarely occur anyway as the tables are only added once. By not having the actual data itself in the acs-object system, subsequent additions and deletions to the reference tables themselves are unaffected by this overhead.


See api-browser

V. Data Model Discussion

The UNSPSC reference data has a data model for handling data revisions. An application can determine any new/revised category based on existing, obsolete data.

VI. User Interface

Their is no end user interface. There needs to be some kind of admin UI to report status and possibly manage updates per requirements.

VII. Configuration/Parameters


VIII. Future Improvements/Areas of Likely Change

A server based update mechanism will be supported. This will allow for tables to be updated (and preferably diffed) instead of being reloaded with a package upgrade. An interface to produce xml/csv from the reference data would be a nice service to the community (allowing legacy applications a way to import this data).

IX. Authors

Jon Griffin